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Introduction 




Welcome to the Sun Workstation. 

This manual is meant to help you get the Sun Workstation Models lOOU (desktop) and 150U 
(rackmount) up and running. The manual has three basic divisions. The first, System Installa- 
tion and Maintenance Guide, gives unpacking and and set-up directions for new desktop and 
rackmount workstations and their subsystems; walks you through UNDC installation procedures 
for Sun systems; and covers the basics on hardware and software operation, maintenance, and 
upgrading. The second section is a reference manual for UNDC commands and utilities relevant to 
system management. The final section includes several installation tutorials. 
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Summary of Contents 

Contents of the System Installation and Maintenance Guide are: 

Chapter 1 — Unpacking and Setting Up the lOOU — is a guide to getting a new Model lOOU 
out of its shipping cartons and setting up the desktop workstation ready to run. If you have 
disk and/or tape sui>systems, work through Chapter 3 next to complete your hardware set up. 

Chapter 2 — Unpacking and Setting Up the 150U — is a guide to getting a new Model 150U 
out of its shipping cartons and setting up the rackmount workstation ready to run. If you have 
disk and/or tape subsystems, work through Chapter 3 next to complete your hardware set up. 

Chapter 3 — Subsystem Set-up — covers unpacking, mounting, and cabling the disk and tape 
subsystems which may be supplied with either the lOOU or the 150U. Also describes how to 
add peripherals to existing subsystems. 

Chapter 4 — Installing UNIX for the First Time — guides you through the procedure for 
installing the UNIX System on a new Sun Workstation from a half-inch or quarter-inch distribu- 
tion tape. Network installation procedures are also covered. 

Chapter 6 — Installing UNIX on Systems Without Tape Support — describes the procedure for 
installing the UNIX System on a Sun Workstation equipped with only a disk drive (no tape), 
over the Ethernet from a system equipped with a tape drive. 

Chapter 8 — System Set-up and Operation — covers basic system set-up and maintenance pro- 
cedures. Topics from uuep and sendmail installation to doing dumps are covered. 

Chapter 7 — Upgrading System Software — gives a brief review of how to upgrade your sys- 
tem to a new software release level. 

Chapter 8 — Hardware Configuration and Expansion — describes the 7-slot Multibus card 
cage in the Model lOOU and the 15-slot cage in the 150U, and provides configuration details for 
each board in the card cage. You must use this chapter to determine placement and switchset- 
tings for new boards when you add boards or peripherals. Also useful for troubleshooting, if 
you need to get inside the card cage and identify the boards. 

Appendix A — Start-up and Bootstrap — discusses the startup and boot functions of the Sun 
Workstation monitor, and lists diagnostic messages which it currently displays. 

The second section of this manual is a reference guide to UNIX commands and utilities of special 
interest to system managers. Section 8 covers the procedures and commands needed for day- 
to-day administration of the UNIX system on the Sun Workstation. The pages are arranged in 
alphabetical order. 

The final section of the manual contains several installation tutorials. 

This manual is still under development and will undergo several revisions before it reaches its 
final form. It will evolve over time to cover the kinds of things you do on a day to day basis; 
and to address the kinds of problems that you are likely to encounter, and what to do about 
those problems. To help direct our development — and to help us maintain the currency and 
accuracy of this material — we have supplied a reader comment sheet at the end of this guide. 
Please use the comment sheet to list errors, omissions and outright lies. Your responses will 
help a great deal in our efforts to keep our documentation cogent. 
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Applicable Documents 

We emphasize that this manual outlines rather than exhausts many of its topics. References to 
applicable documents supplied with your system are given throughout, however, and we urge 
you to read these documents when you can. 

Table 1: Hardware and System Documentation 



Hardware and System Documentation 



Part 
Number 



Description 



800-0277 Fujitsu M2311K/2312K Microdisk Drives CE Manual 

800-0274 Interphase SMD 2180 Storage Module Controller/Formatter User's Guide 

800-0277 Fujitsu M2311K/M2312K Microdisk Drives CE Manual 

800-0339 Sun 1024 Video Board User Manual 

800-0393 3COM 3C400 Multibus Ethernet Controller Reference Manual 

800-0398 Sun Color Video Board User's Manual 

800-0402 User's Guide for the Sun Workstation Mouse Subsystem 

800-0415 Sun 1/4" Tape Interface User Manual 

800-0485 Power Drain Requirements for Sun Workstation Boards 

800-0620 CPC TAPEMASTER Product Specification 

800-0622 CPC TAPEMASTER Application Note 

800-0623 CDC Streaming Tape Unit 9218X Reference Manual 
(1/2" Tape Drive) 

800-0628 Archive Product Manual 

(Sidewinder 1/4" Streaming Cartridge Tape Drive) 

800-1000 Philips Preliminary Service/Operator Manual High Resolution 
17" CRT Display 

800-1002 BARCO GD 33 Color Display 120VAC Operation Instruction 
(13" Color Monitor Manual) 

800-1003 BARCO Color Display CD 251 120/220 VAC Operation Guide 
(19" Color Monitor Manual) 

800-1007 Fujitsu M228X Fixed Disk Unit CE Manual 
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Hardware and System Documentation 



Part 
Number 



Description 



800-1011 Fujitsu M2351A/AF Mini-Disk Drive CE Manual 

800-1005 Xylogics Model 450 Peripheral Processor SMD Disk Subsystems 
Maintenance and Reference Manual 

800-1052 Zilog Serial Communications Controller Technical Manual 

800-1104 Fast Floating-Point Processor System Integration Manual 



Table 2: Software Documentation 



Part 
Number 



Software Documentation 



Description 



800-1107 User's Manual for the Sun Workstation 

800-1108 System Interface Manual for the Sun Workstation 

800-1115 Programmer's Reference Manual for SunCore 

800-1116 Programmer's Reference Manual for Sun\\^ndows 

800-1117 System Internals Manual for the Sun Workstation 



Notations Used In This Guide 

References to commands and utilities from the User's Manual for the Sun UNIX System and the 
System Interface Manual for the Sun UNIX System use the notation: 

passwd(l) 

to indicate the passwd page in section 1 of the User's Manual. (The User's Manual contains sec- 
tions 1, 6, and 7.)** Similarly, passwd(S) means refer to the passwd manual page in section 5 
of the System Interface Manual. (The System Interface Manual contains sections 2, 3, 4, and 
5.) The notation spline(lG) means that this is a Graphics command in section 1 of the User's 
Manual. Finally, /etc/reboot(S) implies that this is a command from section 8, which is in this 
manual. (The System Manager's Manual contains section 8.) 



*• For an explanation of this weird numbering scheme, see the Introduction to the Sun UNIX Sy$tem 
Manuds in the User's Manual. 
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Throughout the examples, there are numbers in the notation: 
Oxnnnn 

A number with Ox in front of it is a hexadecimal (base 16) number. Those wishing more infor- 
mation should consult any of the literature on the C programming language. 

Finally, this manual provides a number of tutorial "walkthrough'' examples which use certain 
formatting conventions. In all these examples, what the user types is shown in boldfaced text, 
like this. The system's response is shown in roman type, like this. Variable items which you 
must substitute — which depend on your system's specific configuration — are shown in italic 
type, like this. Be especially careful with all such substitutions. Lastly, text which appears 
[ within brackets ] is commentary; usually, we use brackets to abbreviate a long series of system 
response messages, or to offer explanation of a process. 
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Chapter 1 
Unpacking and Setting up the lOOU 



This chapter outlines how to unpack and set up your new Sun Model lOOU and some of its peri- 
pherals (subsystems are covered in the chapter Subsystem Set-up). 



If you arc upgrading your Sun Model 100 rather than starting with a system 'fresh from the 
box/ please heed the warning on the front page of this manual. Sun-1 systems which are 
upgrading must not attempt to install this release of the system until all Multibus memory has 
been removed or disabled, and — for an upgrade from a Xylogics 440 to a Xylogics 450 — 
cabling has been re-routed. Disk switch settings may also need to be reset. Make sure you have 
followed the procedures given in Sun's Upgrade Installation Guide before proceeding. 



If you are adding boards and/or peripherals to an existing system, the chapter on Hardware 
Configuration and Expansion will give you the information you need. 

1.1. Safety Precautions 

DO NOT attempt procedures which are not described in this manual; if you do, you may void 
your warranty. Please refer all servicing not described in this document to qualified service per- 
sonnel. If in doubt, contact your authorized Sun service representative. 

Observe common-sense safety precautions as you would for any electrical or electronic equip- 
ment. Always disconnect the power cord before opening any system enclosure. 



Even after power is disconnected from the workstation, very high voltages remain in the capacitors 
behind the picture tube. It takes about ten minutes for the capacitors to lose their charge. 



The following sections contain set-uij and configuration specifications for the Sun Workstation. 
Consult the additional hardware manuals supplied with your workstation (and with user- 
supplied Multibus accessory boards, if any) for further information and precautions. 

1.2. Environmental Considerations 

This section describes the environmental requirements for the Sun Model lOOU. 

Attention: This equipment generates, uses, and can radiate radio frequency energy and if not 
installed and used in accordance with the instructions manual, may cause interference to radio 
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communications. It has been tested and found to comply with the limits for a Class A comput- 
ing device pursuant to Subpart J of Part 15 of FCC Rules, which are designed to provide rear 
sonable protection against such interference when operated in a commercial environment. 
Operation of this equipment in a residential area is likely to cause interference, in which case 
the user at his own expense will be required to take whatever measures may be required to 
correct the interference. 



1.2.1. Physical Environment 

The Sun Model lOOU is manufactured for the following physical environment: 

Table 1-1: Physical Environment 



Operating Nori' Oper ating 



Ambient Temperature 

Humidity 

( Non-condensing) 

Altitude 



IO'C-40'C 
5% -90% 



-40'C-65'C 
5% - 90% 



10,000 feet 40,000 feet 



1.2.2. Power Drain Requirements 

Model lOOU desktop workistations are equipped with a 200 watt four-output power supply, 
which delivers + 5, -5, + 12, and -12 volts.* 

Table 1-2: Power Supply Ratings 



,, ,^ Maximum 

^'^''^' Current in Amps 



+ 5 

-5 

+ 12 

-12 



35.0 
1.5 
4.0 
1.5 



It is possible that a full card cage will exceed the ratings of this supply. The table which fol- 
lows shows the power consumption of each Sun-supplied board. Boards documented are those 
current for this release. 



1 NOTE that this rating is for the Model lOOU current with this release; older systems (pre-0.4 
release of August 1983) have 175 watt, 30 amp power supplies. The peak amperage for these sys- 
tems is: + 5: 30 amps; -5: 2.0 amps; + 12: 4.0 amps; -12: 2.0 amps. 



1-2 
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Table 1-3: Power Consumption of Boards 



PART 
NUMBER 


BOARD 


AMPS 
Q -hSV 


TOTAL 
WATTS 


370-1012 


Xylogics SMD Disk Controller Board 


8.0 


45 


370-1021 


Sky Floating Point Processor 


4.0 


20 


501-0289 


Color Display Controller 


6.0 


36 


590-0059 


Black and White Display Controller 


5.0 


25 


590-0217 


Interphase SMD Disk Controller Board 


4.0 


23 


590-0288 


10Mbit Ethernet Board 


5.0 


31 


590-0502 


1/2-inch Tape Controller Board 


4.0 


20 


590-0526 


1/4-inch Tape Controller Board 


3.0 


15 


590-1007 


Sun-2 CPU Board, 
Keyboard, and Mouse 


6.0 


30 


590-1013 


IM Memory Board 


3.0 


15 


590-1013 


Sun-2 (low power) Memory Board 


2.5 


13 



Note that the keyboard and mouse draw their power from the CPU board. 

Review the above list carefully to determine exactly what configuration of boards you can have 
in the card cage. If you get boards from other suppliers, make sure you obtain the current 
power consumption information from them, so that you can factor that information in with the 
list above. Overloading the rated capacity of the power supply can cause system malfunction 
(which often shows up as "glitches'^ on the video screen), and may damage the power supply. 

1.3. Receipt and Unpacking Instructions 



Note that the shipping weight of the Sun Workstation and its shipping carton is approximately 105 
pounds. The weight of the workstation itself is about 90 pounds. 



1. When you receive your shipment, inspect all shipping cartons immediately for evidence of 
damage. If any shipping carton is severely damaged, request that the carrier^s agent be 
present when the carton is opened. If the carrier's agent is not present when a carton is 
opened and the contents are found to be damaged, keep all contents and packing materials 
for the agent's inspection, 

2. To open the shipping carton, cut the binding straps on it with a knife or scissors. The ship- 
ping carton is in the form of a square 'tube' with two lids on it, one on the bottom, and one 
on the top. The workstation is encased in styrofoam packing materials inside the lids. 

3. Remove the top lid from the 'tube', and you will find the keyboard, the distribution tape(s), 
the power cord, and an envelope containing manuals in the recesses in the top of the packing 
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material. Remove these items. 
4. Lift out the rubber and styrofoam packing material (the fit is fairly tight; try rocking it 
out). At this point you may find a mouse and mouse pad tucked along the side of the moni- 
tor; if you ordered an 84-MByte disk subsystem, these will be packed with it instead. 




5. Remove the square 'tube' from its bottom lid. Don't try to lift the Sun Workstation out of 
the shipping carton: it's too heavy. When you remove the 'tube' from the bottom lid, the 
workstation is left standing in the bottom piece of packing material. You can then lift the 
workstation out of the bottom shipping material, remove the plastic wrapping, and place the 
workstation on its working surface. 

We recommend that you save the salvageable shipping cartons and packing material for future 
use in case the product must be reshipped. 



1.4. Set-up 

The following subsections describe how to cable up your Sun Model lOOU and its basic peri- 
pherals: 



CA UTION: Before plugging in the power cord of any component of your Sun system, be sure 
that the line power supply voltage and frequency are as specified on the back panel of your 
workstation. Use only three-prong (grounded) outlets. Always disconnect power before opening 
any system enclosure or servicing any system component. All servicing should be performed by 
qualified personnel. 
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1.4.1. Keyboard and Mouse 

The Sun keyboard should be plugged into the connector labelled "KEYBOARD" on the works- 
tation back panel. If you wish to use the keyboard as your console input device (as is normally 
done) you must power-on the workstation AFTER plugging in the keyboard. The Sun resident 
PROM monitor will try to use serial port A for input if it does not find an attached keyboard. 

Plug the mouse into the "MOUSE" connector on the backpanel. 



® 
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1.4.2. Ethernet 

If you purchased a system with Ethernet, your system is shipped with the Ethernet Controller 
Board installed in your workstation's Multibus card cage. You will receive a package containing 
the transceiver and transceiver cable necessary to complete implementation of the Ethernet for 
a single workstation, and an Ethernet Controller Reference Manual. The coaxial cable necessary 
to implement a network with multiple machines may be purchased separately from Sun. 

Setting up an Ethernet with all Sun-supplied components is fairly straightforward: 

1. Terminate the 50-ohm coaxial cable by placing a transceiver at both ends. Screw the cable 
into the transceiver N-connectors; cover the open N-connector on each transceiver with a 
terminator. In lieu of a transceiver, you may terminate the cable with two barrel connectors 
and terminators. Handle the coaxial cable with some care, as it is fragile; don't run it in an 
area where it may be rus over. 

2. For each workstation, plug one end of the transceiver cable into the 15-pin D-connector on 
the transceiver, and the other end into the "ETHERNET 10 MBIT" connector on the 
workstation backplane. 

Please note that there are certain cabling limitations which must be observed for proper Ether- 
net implementation: 
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Table 1-4: Ethernet Cabling Limitations 



Ethernet Cabling Limitations 



MAXIMUM contiguous length of coaxial cable segments 500.0 meters 



Distance between transceivers* 



2.5 meter 
sections 



MAXIMUM length of transceiver cable 



50.0 meters 



* Transceivers must be placed at 2.5 meter intervals along the coaxial cable. These intervals 
are marked with a black band on the cable. If you want to spread transceivers along a greater 
length of cable, make sure the distance between any two transceivers is a multiple of 2.5 meters. 

For more information, see the Ethernet manual shipped with your system. If you have ques- 
tions about repeaters or non-stardard Ethernet configurations, please contact Sun Microsystems. 



1.4.3. Asynchronous Serial Ports 

You may attach a terminal, modem, printer, plotter, or other device which uses the RS-232 
interfaces, to one of the serial port connectors labelled ^'ES232 A" and "RS232 B" on the back 
panel. 

The serial ports on the Sun Workstation were designed primarily for connecting output peri- 
pherals, such as printers and plotters, and can drive these output lines at speeds up to 19.2 
Kbaud. Both ports provide the CTS, RTS, DTR, DSR, and DCD control lines required by 
some devices (such as modems) in addition to the transmit and receive lines; the ports generate 
DTR and RTS, and pay attention to DSR, CTS, and DCD. Both ports are also wired as DTE 
(Data Terminal Equipment) ports, and thus permit direct connection of modems. Computers 
and other DTE devices can be connected using the null modem cable supplied by Sun. See the 
Asynchronous Serial Ports section of the Hardware Configuration and Expansion chapter for wir- 
ing specifications. 



NOTE that older workstations (shipped prior to the 1.0 Release) have serial port A configured 
as a DCE (Data Communications Equipment) and serial port B configured as a DTE. In addi- 
tion, only serial port A on the older workstations has full modem control. This means that 
external cables built for the Sun-1 or Sun-1.5 CPU may have to be modified to work correctly 
with the Sun-2 CPU, or a null modem cable (such as that supplied by Sun) may be required. 
See the Asynchronous Serial Ports section of the Hardware Configuration arid Expansion chapter 
for wiring specifications. 
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Chapter 2 
Unpacking and Setting up the 150U 



This chapter outlines how to unpack and set up your new Sun Model 150U and some of its peri- 
pherals (subsystems are covered in the chapter Subsyatcm Set-up). 



If you au*e upgrading your Sun Model 150 rather than starting with a system *fresh from the 
box,' please heed the warning on the front page of this manual. Sun-1 systems which are 
upgrading must not attempt to install this release of the system until all Multibus memory has 
been removed or disabled, and — for an upgrade from a Xylogics 440 to a Xylogics 450 — 
cabling has been re-routed. Disk switch settings may also need to be reset. Make sure you have 
followed the procedures given in Sun's Upgrade Inttallation Guide before proceeding. 



If you are adding boards and/or peripherals to an existing system, the chapter on Hardware 
Configuration and Expansion will give you the information you need. 

2.1. Safety Precautions 

DO NOT attempt procedures which are not described in this manual; if you do, you may void 
your warranty. Please refer all servicing not described in this document to qualified service per- 
sonnel. If in doubt, contact your authorized Sun service representative. 

Observe common-sense safety precautions as you would for any electrical or electronic equip- 
ment. Always disconnect the power cord before opening any system enclosure. 



Even after power it disconnected from the workstation, very high voltages remain in the capacitors 
behind the picture tube. It takes about ten minutes for the capacitors to lose their charge. 



The following sections contain set-up and configuration specifications for the Sun Rackmount 
Workstation. Consult the additional hardware manuals supplied with your workstation (and 
with user-supplied Multibus accessory boards, if any) for further information and precautions. 

2.2. Environmental Considerations 

This section describes the environmental requirements for the Sun Model 150U. 

Attention: This equipment generates, uses, and can radiate radio frequency energy and if not 
installed and used in accordance with the instructions manual, may cause interference to radio 
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communications. It has been tested and found to comply with the limits for a Class A comput- 
ing device pursuant to Subpart J of Part 15 of FCC Rules, which are designed to provide rea- 
sonable protection against such interference when operated in a commercial environment. 
Operation of this equipment in a residential area is likely to cause interference, in which case 
the user at his own expense will be required to take whatever measures may be required to 
correct the interference. 



2.2.1. Physical Environment 

The Sun Model 150U is manufactured for the following physical environment: 

Table 2-1: 150U Physical Environment 



Operating Non- Operating 



Ambient Temperature 

Humidity 

( Non-condensing) 

Altitude 



10'C-40"C 
5% -90% 



-40'C-65°C 

5% - 90% 



10,000 feet 40,000 feet 



2.2.2. Power Drain Requirements 

Model 150U rackmount systems are supplied with a 1000 watt, four-output power supply, which 
delivers + 5, -5, + 12, and -12 volts. The power supply is rated as follows: 

Table 2-2: Model 150U Power Consumption 



Voltage 



Maximum 
Current in Amps 



+ 5 

-5 

+ 12 

-12 



150.0 

5.0 

10.0 

10.0 



It is unlikely that a full card cage will exceed the ratings of this supply. The table which fol- 
lows shows the power consumption for Sun-supplied boards. Boards documented are current 
with this release. 
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Table 2-3: Power Consumption of Boards 



PART 
NUMBER 


BOARD 


AMPS 
Q +5V 


TOTAL 
WATTS 


370-1012 


Xylogics SMD Disk Controller Board 


8.0 


45 


370-1021 


Sky Floating Point Processor 


4.0 


20 


501-0289 


Color Display Controller 


6.0 


36 


590-0059 


Black and White Display Controller 


5.0 


25 


590-0217 


Interphase SMD Disk Controller Board 


4.0 


23 


590-0288 


10Mbit Ethernet Board 


5.0 


31 


590-0502 


1/2-inch Tape Controller Board 


4.0 


20 


590-0526 


1/4-inch Tape Controller Board 


3.0 


15 


590-1007 


Sun-2 CPU Board, 
Keyboard, and Mouse 


6.0 


30 


590-1013 


IM Memory Board 


3.0 


15 


590-1013 


Sun-2 (low power) Memory Board 


2.5 


13 



Note that the keyboard and mouse draw their power from the CPU board. 

Review the above list carefully to determine exactly what configuration of boards you can have 
in the card cage. If you get boards from other suppliers, make sure you obtain the current 
power consumption information from them, so that you can factor that information in with the 
list above. Overloading the rated capacity of the power supply can cause system malfunction 
(which often shows up as "glitches" on the video screen), and may damage the power supply. 

2.3. Receipt and Unpacking Instructions 

The basic Model li^OU is shipped in two separate cartons: one contains the Sun Workstation 
video monitor on its pedestal, and the second contains a rack-mountable metal enclosure with 
the workstation card cage and power supply. Each subsystem ordered comes in its own carton 
— see the chapter Subsystem Set-up for unpacking instructions. You may also find yourself 
with a few small boxes: the Sun System documentation is shipped in its own package, as are 
the brackets and power supply for the 169-MByte disk. 

When you receive your shipment, inspect all shipping cartons immediately for evidence of dam- 
age. If any shipping carton is severely damaged, request that the carrier's agent be present 
when the carton is opened. If the carrier's agent is not present when a carton is opened and the 
contents are found to be damaged, keep all contents and packing materials for the agent's 
inspection. 

The following two subsections describe how to unpack the Model 150U monitor and card cage 
enclosure. Mounting instructions for the card cage enclosure are also given. 
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2.3.1. 150U Monitor — Unpacking 



Note that the shipping weight of the Model 150U monitor and its shipping carton is approximately 
80 pounds. The weight of the monitor itself is about 70 pounds. 



1. To open the monitor's shipping carton, cut the binding straps on it with a knife or scissors. 
The shipping carton is in the form of a square 'tube' with two lids on it, one on the bottom, 
and one on the top. The monitor is cioicased in styrofoam packing materials inside the lids. 




2. Remove the top lid from the 'tube\ and you will find the keyboard, the power cord, the dis- 
tribution tape(8), and an envelope containing manuals in the recesses in the top of the pack- 
ing material. Remove these items. 

3. Lift out the rubber and styrofoam packing material (the fit is fairly tight; try rocking it 
out). At this point you may find a mouse and mouse pad boxed and tucked along the side 
of the monitor; if you ordered an 84-MByte disk subsystem, these will be packed with it 
instead. 

4. Remove the square 'tube' from its bottom lid. Don't try to lift the monitor out of the ship- 
ping carton: it's too heavy. When you remove the 'tube' from the bottom lid, the monitor is 
left standing in the bottom piece of packing material. Two people can then lift the monitor 
out of the bottom shipping material, remove the plastic wrapping, and place the monitor on 
its working surface. 

We recommend that you save the salvageable shipping carton and packing material for future 
use in case the product must be reshipped. 
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2.3.2. 150U Card Cage Enclosure — Unpacking and Mounting 



Note that the shipping weight of the Model 150U enclosure and its shipping carton is approxi- 
mately 60 pounds. The weight of the enclosure itself is about 50 pounds. 



1. Open the enclosure's shipping carton as you did the monitor's. 

2. Remove the top lid from the shipping 'tube', and you will find a cardboard piece with the 
door for the enclosure; power cord; and extension keyboard, mouse, and video cables on it. 
Take these items off and set them aside. 

3. Pull up the cardboard and styrofoam packing material, and you will expose the unit, covered 
in plastic. 

4. Remove the square 'tube' from its bottom lid. Don't try to lift the enclosure out of the ship- 
ping carton: it's too heavy. When you remove the 'tube' from the bottom lid, the unit is left 
standing in the bottom piece of packing material. Two people can then lift the enclosure out 
of the bottom shipping material, using the handles on its sides. 

We recommend that you save the salvageable shipping carton and packing material for 
future use in case the product must be reshipped. 

5. The M150U enclosure comes supplied with a set of clips containing captive nuts, and a set of 
bolts for bolting the unit into a standard 19-inch rack. To mount the enclosure, clip the 
clips into the holes in the vertical metal rail in the rack. Then commandeer two cohorts to 
position the unit in the rack while you secure it by the bolts provided. 

6. Lastly, slip the enclosure front door on. If you mount the unit with the door on, you run 
the risk of shearing off the front light and switch. 

2.4. Set-up 

The following subsections describe how to cable up your Sun Model 150U and its basic peri- 
pherals. 



CAUTION: Before plugging in the power cord of any component of your Sun system, be sure 
that the line power supply voltage and frequency are as specified on the back panel of your 
workstation. Use only three-prong (grounded) outlets. Always disconnect power before opening 
any system enclosure or servicing any system component. All servicing should be performed by 
qualified personnel. 



2.4.1. Keyboard and Mouse 

The Sun keyboard should be plugged into the connector labelled "KEYBOARD" on the card 
cage back panel. If ^ou wish to use the keyboard as your console input device (as is normally 
done) you must power-on the workstation AFTER plugging in the keyboard. The Sun resident 
PROM monitor will try to use serial port A for input if it does not find an attached keyboard. 

Plug the mouse into the "MOUSE" connector on the back panel. 
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2.4.2. Ethernet 

If you purchased a system with Ethernet, your system is shipped with the Ethernet Controller 
Board installed in your workstation's Multibus card cage. You will receive a package containing 
the transceiver and transceiver cable necessary to complete implementation of the Ethernet for 
a single workstation, and an Ethernet Controller Reference Manual. The coaxial cable necessary 
to implement a network with multiple machines may be purchased separately from Sun. 

Setting up an Ethernet with all Sun-supplied components is fairly straightforward: 

1. Terminate the 50-ohm coaxial cable by placing a transceiver at both ends. Screw the cable 
into the transceiver N-connectors; cover the open N-connector on each transceiver with a 
terminator. In lieu of a transceiver, you may terminate the cable with two barrel connectors 
and terminators. Handle the coaxial cable with some care, as it is fragile; don't run it in an 
area where it may be run over. 

2. For each workstation, plug one end of the transceiver cable into the 15-pin D-connector on 
the transceiver, and the other end into the ^'ETHERNET 10 MBIT" connector on the card 
cage enclosure backplane. 

Please note that there are certain cabling limitations which must be observed for proper Ether- 
net implementation: 

Table 2-4: Ethernet Cabling Limitations 



Ethernet Cabling Limitations 



MAXIMUM contiguous length of coaxial cable segments 500.0 meters 



Distance between transceivers* 



2.5 meter 
sections 



MAXIMUM length of transceiver cable 



50.0 meters 



* Transceivers must be placed at 2.5 meter intervals along the coaxial cable. These intervals 
are marked on the cable with a black band. If you want to spread transceivers along a greater 
length of cable, make sure the distance between any two transceivers is a multiple of 2.5 meters. 

For more information, see the Ethernet manual shipped with your system. If you have ques- 
tions about repeaters or non-stardard Ethernet configurations, please contact Sun Microsystems. 

2.4.3. Asynchronous Serial Ports 

You may attach a terminal, modem, printer, plotter, or other device which uses the RS-232 
interfaces, to one of the serial port connectors labelled "RS232 A" and "RS232 B" on the back 
panel. 
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NOTE that older workstations (shipped prior to the 1.0 Release) have serial port A configured 
as a DCE (Data Communications Equipment) and serial port B configured as a DTE. In addi- 
tion, only serial port A on the older workstations has full modem control. This means that 
external cables built for the Sun-1 or Sun-1.5 CPU may have to be modified to work correctly 
with the Sun-2 CPU, or a null modem cable (such as that supplied by Sun) may be required. 
See the Aaynchronoua Serial Ports section of the Hardware Configuratiori and Expansion chapter 
for wiring specifications. 



The serial ports on the Sun Workstation were designed primarily for connecting output peri- 
pherals, such as printers and plotters, and can drive these output lines at speeds up to 19.2 
Kbaud. Both ports provide the CTS, RTS, DTR, DSR, and DCD control lines required by 
some devices (such as modems) in addition to the transmit and receive lines; the ports generate 
DTR and RTS, and pay attention to DSR, CTS, and DCD. Both ports are also wired as DTE 
(Data Terminal direct connection of modems. Computers and other DTE devices can be con- 
nected using the null modem cable supplied by Sun. See the Asynchronous Serial Ports section 
of the Hardware Configuration and Expansion chapter for wiring specifications. 
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Subsystem Set-Up 



This chapter gives step-by-step instructions on how to unpack, mount, and cable up the various 
disk and tape subsystems which may be supplied with either the Model lOOU or Model 150U. 

This chapter also gives directions on how to add a second Fujitsu M2312K (84-MByte unformat- 
ted), M2284 (169-MByte unformatted), or M2351 (474-MByte unformatted) drive to an existing 
Sun system. For details on configuring disk/tape controller boards, see the Hardware 
Configuration and Expansion chapter. 

3.1. M2312K (Fujitsu 84-MByte) Disk 

Your Sun Workstation may be supplied with a disk subsystem which is the Fujitsu Model 
M2312K disk drive. The Fujitsu disk drive uses the industry-standard SMD interface which is 
supported by either the Interphase SMD 2180 disk controller or the Xylogics 450 SMD disk con- 
troller supplied with your disk subsystem. 



Note that if you are upgrading from an Interphase controller to a Xylogics controller, the DIP 
switches on the top surface of the disk drive must be re-set. For an Interphase controller, the 
proper settings are: on DIP Switch 2, switches 2, 4, 5, and 7 ON; switches 1, 3, and 6 OFF; on 
DIP Switch 3, switch 3 ON; all others OFF. For a Xylogics 440 or 450 controller, the proper 
settings are: on DIP Switch 2, all switches ON; on DIP Switch 3, switch 3 ON; all others OFF. 



Two disk drives may be attached to a single SMD controller. Fujitsu disk drives are shipped in 
a box nested inside another box. The package containing the disk drive is wrapped in a plastic 
bag. To unpack, mount, and cable up the subsystem, follow the procedures below. 



Note that the shipping weight of the 84-MByte Disk Subsystem and its shipping carton is approxi- 
mately 85 pounds. The weight of the unit itself is about 75 pounds. 



1. Open the disk's shipping carton by cutting its binding straps with a knife or scissors. 

2. Open the outer shipping carton and remove the top styrofoam piece. This exposes packing 
foam containing several components (these vary depending on your system configuration): 
manuals, a power cord, Ethernet cables and transceiver, mouse and pad, and — for a 150U 
only — the mounting hardware for the disk subsystem. Remove these items and set them 
aside. 
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3. Remove the foam piece and the cardboard below it; you'll see four styrofoam corner pieces 
and another box. Remove the inner box from the shipping carton. 

4. Peel oflf the tape which seals this box. DON'T CUT OPEN the box, or you may damage 
the finish on the unit. Remove the metal unit — this holds the 84-MByte disk subsystem, 
and may also contain a 1/4-inch tape drive. 

We recommend that you save the salvageable shipping carton and packing material for 
future use in case the product must be reshipped. 

5. If you are mounting the subsystem in a 19-inch rack, proceed with the next three steps; 
otherwise, unlock the heads on the disk drive by following the procedure in step 7, and 
then proceed with cabling in step 9. 

6. To mount the subsystem, first mount the slides at the chosen position in the rack. 

7. Before carefully sliding the subsystem into the rack, you must unlock the heads on the disk 
drive. The head lock for the 84-MByte drive is on the bottom of the subsystem enclosure, 
so you must either tilt or elevate the enclosure to get at it. To unlock the heads, use a large 
screwdriver to rotate the white plastic knob on the bottom of the unit to the OFF position. 
ALWAYS lock the heads by rotating this knob to the ON position before moving the drive 
— even from table to table. More detailed instructions are in the Fujitsu Microdisk Drives 
CE Manual. 



8. Now, slide the subsystem into the rack. 

9. The disk subsystem is attached to either the Model lOOU workstation backpanel or the 
Model 150U card cage enclosure backpanel via two flat ribbon cables. The (wider) control 
cable comes out of the back of the Fujitsu disk drive enclosure, and is labelled "DISK". 
This cable plugs into the connector labelled 'DISK COMMAND' on the Sun backpanel. The 
(narrower) data or "B" cable for each of up to four drives plugs into one of the four SMD-B 
connectors labelled 'DISK DATA #x' on the back panel, where a; is through 3. The first 
disk drive must be cabled to connector 'DISK DATA #0'; the second should be cabled to 
'DISK DATA #r. 

The disk controller installed in the card cage of both the Model lOOU and the 150U is a Xylogics 
450 controller which can control up to four drives; however, the system is configured for a max- 
imum of two drives per controller. As shipped, each drive is configured as the first drive, that is, 
unit number 0, by setting section 4 of SWl (accessible at the top of the drive) to ON and all 
other sections to OFF. SW2 and SW3 are set correctly as they come from Sun, and should be 
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left alone: SW3 should have section 3 OFF and all others ON; and SW2 should be properly set 
for your SMD controller type. If you have a Xylogics 450 SMD Disk Controller, SW2 should 
have all sections ON; if you have an Interphase 2180 SMD Disk Controller, SW2 should have 
sections 2, 4, 5, and 7 OiVand all others OFF. 

The Fujitsu subsystem is very simple to operate; it has only a power cord and an on-ofif switch. 
However, we suggest that you take some time to look through the installation and operation 
sections of the Fujitsu manual before using the drive, to understand general operating require- 
ments and precautions. 

3.1.1. M2312K (Fujitsu 84-MByte) Disk Expansion 

If you are adding a second drive to your system, a bit of configuration work is necessary. Basi- 
cally, you have to do the following: 



CAUTION: Turn oflf the power and disconnect the power cord before opening up the Sun 
Workstation's enclosure, doing cabling of any sort, or altering peripheral/board configurations. 



1. Remove the four terminator packs from your expansion drive. The terminator packs are 
required only on the last disk drive in a daisy-chain configuration. If you ordered your 
expansion drive from Sun, the terminator packs should already have been removed when 
you receive the drive. 

The terminator packs are located on the drive circuit board inside the chrome chassis. To 
get to them, unscrew the two Phillips screws on the chrome cover (at the rear of the drive), 
and lift off the cover. The four terminator packs are the chips just behind the 60-pin com- 
mand cable connector. 

2. Set the new drive's logical address to unit number 1: set sections 1 and 4 on switch SWl 
to ON, and leave the other sections OFF. To do this, you need to remove the outer (white 
metal) and inner covers of the subsystem housing: SWl is accessible at the top of the drive 
itself. The other switches, SW2 and SW3, should be left as set originally; see the previous 
section for proper settings. 

3. Daisy chain the drives together using the special cable which comes with the expansion 
drive. The cable has several female connectors along it (which connect to the disk com- 
mand cables), and ends in a single male connector (which connects to the workstation back- 
panel). Connect each disk's command cable to one of the female connectors along the 
expansion cable, making sure that the drive with the terminator packs is the last drive in 
the chain. Then connect the male end of the expansion cable to the ^DISK COMMAND' con- 
nector on the Sun baickpanel. 

4. Plug the 25-pin data cable for drive unit #0 into the 'DISK DATA #0' connector on the Sun 
backpanel, and the data cable for drive unit ^1 (your expansion drive, if you followed 
these procedures) into 'DISK DATA j^V. 

No changes to the Xylogics 450 Disk Controller Board are necessary. 

Before you mount and/or power up the drive, make sure you have followed the directions for 
unlocking the heads given in the previous section. 
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3.2. M2284 (Fujitsu 169-MByte) Disk 

The 169-MByte disk subsystem is currently shipped in several boxes: the disk drive itself, the 
power supply for the subsystem, and the mounting hardware for a 19-inch rack each come pack- 
aged separately. 

When you follow the unpacking and mounting procedures below, we recommend that you have 
the Fujitsu M228X Fixed Disk Unit, Customer Engineering Manual close at hand. This manual 
contains information essential to the process. 



Note that the shipping weight of the 169-MByte Disk Subsystem and its shipping carton is approzi- 
mately 90 pounds. The weight of the unit itself is about 80 pounds. 



1. Open the 169-MB3rte disk's outer shipping carton by removing the four white plastic pins 
on the lid (squeeze together wings and pull), and then lifting off the lid. 

2. When the lid is removed, the internal carton containing the disk subsytem is exposed. Lift 
out the internal carton, and take off the corner pads. 

3. Cut open the internal carton, and remove the styrofoam packing material. This exposes 
the power and control cables, on the sides of the box; the front panel for the unit; and the 
subsystem itself, wrapped in a polyethylene bag. 

4. With another person, lift the unit out of its bottom pad. Grasp the unit at the bottom to 
avoid damage to the sub-assemblies. 

We recommend that you save the salvageable shipping carton and packing material for 
future use in case the product must be reshipped. 

5. Before applying power to the subsystem, you must unlock the spindle, the actuator, and 
the motor on the disk drive. These are locked during shipment to protect the subsystem, 
and must be locked any time the unit is moved. For procedures, see the Fujitsu M228X 
Fixed Disk Unit, Customer Engineering Manual, sections 3.4.3, 3.4.4, and 3.4.5, respectively. 

If you are mounting the subsystem, and you are mounting it such that you can get to its 
underside when it is mounted (necessary to unlock the spindle), you should mount the unit 
before unlocking the spindle, actuator, and motor for maximum protection. Go on with 
step 6 for mounting instructions. 

0. To mount the subsystem, first mount the slides at the chosen position in the rack. Have 
one or two brawny folks around to help you lift the unit gently into position. When you 
are completely through with sliding the disk around, you can screw the pair of retaining bars 
onto the front of the subsystem, and snap on the front panel. 

7. The M2284 disk drive is connected to its power supply unit via three cables. 



CA.UXION: Turn off the power and disconnect the power cord before opening up the Sun 
Workstation's enclosure, doing cabling of any sort, or altering peripheral/board configurations. 



There are two power cables known as the 'A' (AC) and 'B' (DC) power cables, and there is 
a power control cable for power-up sequencing when multiple disk drives are installed. The 
*A' cable (12- pin) connects to PWl near the center rear of the power supply unit. The 'B' 
cable (15-pin) connects to PW2 near the top right rear of the unit. The power control 
cable (9-pin) connects to CN18, just to the left of PW2. 
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8. There are two switches of interest on the power supply unit. The POWER ON/OFF switch 
must be left ON all the time after installation. The LOCAL/REMOTE switch must be set to 
REMOTE at all times. 

9. The power supply unit itself should be connected to a standard AC line. The brown wire 
in the line goes to the first Phillips screw of the series starting at the lower left rear of the 
power supply unit. The screw is 'under' the label "INPUT". The blue wire in the line goes 
to the second screw, under the label "AC". The green wire goes to "FG", frame ground. 

10. After connecting the M2284 to its power supply, hook up its control and data cables as fol- 
lows. 

The M2284 is connected to the card cage backpanel via two flat ribbon cables. The wider 
of the cables is a 60-pin control cable. Plug the control cable into the socket labelled 'DISK 
COMMAND' on the backpanel. The narrower cable (25-pin) is the disk data cable; plug it 
into the socket labelled 'DISK DATA #a;' on the backpanel, where jr is through 3. The first 
disk drive must be cabled to connector 'DISK DATA 5^0'; the second must be cabled to the 
'DISK DATA #r connector. 

After connecting the flat ribbon cables to the backpanel of the Sun Workstation, connect 
the other ends of the cables to the disk drive. The 60-pin cable (connected to 'DISK CO\t 
MAND' on the Sun Workstation backpanel) must be inserted into location '0M2' in the disk 
drive. The narrower cable (connected to 'DISK DATA ^z' on the Sun Workstation back- 
panel) must be inserted into location 'OM3' in the disk drive. The red stripe on both 
cables should be to your left as you look at the disk drive from the back. Both cables 
should be passed through the cable-routing bracket located directly above their respective 
termination points on the disk drive^ At the same time, the grounding straps from the rib- 
bon cables' shield must be secured using the hardware on the routing bracket. 

11. Make sure that the line-termination board is securely seated into 'OMl' on the disk drive 
(if you have more than one disk, the line-termination board is required only on the laet disk 
drive in a daisy-chain configuration). The grounding strap must be fastened to 'TRMl-2' 
on the terminal block (marked "OV(2)"). 

For more information on disk interface and cables, refer to sections 3.5.3 and 3.5.5 of the 
Fujitsu 228X Customer Engineering Manual. 

The disk controller itistalled in the card cage of both the Model lOOU and the 150U is a Xylogics 
450 controller which can control up to four drives; however, the system is configured for a max- 
imum of two drives per controller. As shipped, each drive is configured as the first drive, that is, 
unit number 0, by setting all sections on switch SWl at location J2/J1 on the CQFM PCB 
assembly to OFF. 
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3.2.1. M2284 (Fujitsu 169-MByte) Disk Expansion 

If you are adding a second drive to your system, a bit of configuration work is necessary. 
Proceed as follows: 



CAUTION: Turn oflf the power and disconnect the power cord before opening up the Sun 
Workstation's enclosure, doing cabling of any sort, or altering peripheral/board configurations. 



1. Remove the terminator board from your first drive, and place it in your new drive, making 
sure it is centered and seated securely into 'OMT on the second drive. 'OMT is the 60-pin 
connector closest to you as you stand at the rear of the drive. The grounding strap must 
be fastened to 'TRMl-2' on the terminal block (marked "0V(2)"). The line-termination 
board is required only on the last disk drive in a daisy-chain configuration. 

2. Set the new drive's logical address to unit number 1, by setting the first section on switch 
SWl (at location J2/J1 on the CQFM PCB assembly) to ON, and leaving the other sections 
OFF. To do this, you need to get to SWl, which is on the circuit board in the PCB chassis 
(the metal housing at the left rear of the drive) which is closest to you if you stand at the 
rear of the drive. The board is labelled CQFM. SWl is the 8-position DIP switch nearest 
the center of the board, just under the 60-pin edge connector. Proceed as follows: 

1. Shut everything down gracefully, remove the drive from the rack (if mounted), and 
lock the spindle. If you can get to the top of the PCB chassis — the metal housing at 
the rear of the drive, next to the motor — without removing the drive from its moor- 
ings, so much the better. 

2. Remove the metal plate from the top of the PCB chassis to expose the four circuit 
boards inside. 

3. Remove the CQFM assembly — the board closest to you as you stand at the rear of 
the drive. 

4. Make sure the first key on SWl is set to ON, and all other keys are OFF. This sets 
the drive's logical address to ^1. SWl is the switch nearest the center of the board. 

5. Put everything back together again. 

3. Daisy chain the drives together using the command cable which comes with the expansion 
drive. Run this cable from the 60-pin command cable socket ('OM2') on the drive with the 
line terminator (your expansion drive, if you followed the procedures above), to 'OMl' on 
the intermediate drive, and run this disk's command cable from 'OMl' to the 'DISK COM- 
MAND' connector on the Sun backpanel. 

4. Plug the 25-pin data cables in. The first disk drive (unit #0) must be cabled to connector 
'DISK DATA #0'; the second (unit #1, the expansion drive if you followed the procedures 
above) must be cabled to the 'DISK DATA #1' connector. 

No changes to the Xylogics 450 Disk Controller Board are necessary. 

Before you mount and/or power up the drive, make sure you have followed the directions for 
unlocking the spindle, actuator, and motor given in the Fujitsu M228X Fixed Disk Unit, Custo- 
mer Engineering Manual, sections 3.4.3, 3.4.4, and 3.4.5, respectively. 
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3.3. M2351 (Fujitsu 474-MByte) Disk 

The 474-MByte disk subsystem is shipped in a single carton, along with its cables. The drive 
itself is shipped in nested boxes, and wrapped in a polyethylene bag. To unpack, mount, and 
cable up the M2351, follow the procedures below. 

We recommend that you have the Fujitsu M2S51A/AF Mini-Disk Drive CE Manual close at 
hand as you follow the instructions; it contains essential information. 

1. Op?!n the 474-MByte disk^s outer shipping carton by cutting the binding straps with a knife 
or scissors, and opening the flaps. 

2. When the box flaps are opened, the shock absorbers surrounding the internal carton are 
exposed. Remove the shock absorbers, and have AT LEAST two people lift out the inter- 
nal carton. 

3. Cut open the internal carton to expose the subsystem itself, wrapped in a polyethylene bag. 
Remove the two nylon straps. 

4. With another person, lift the unit out of its bottom pad. Grasp the unit at the bottom to 
avoid damage to the sub-assemblies. 

We recommend that you save the salvageable shipping carton and packing material for 
future use in case the product must be reshipped. 

5. Remove the cover on the drive. Loosen the two Phillips screws that hold the card cage 
upright, and gently pivot and lift the card cage to a horizontal position to expose the 
'Vibration Preventative Block* (a piece of styrofoam) under the disk enclosure housing. 
Remove the *VPB'. Return the card cage to its upright position, and tighten the screws. 

6. Locate the rotary actuator ('VCM') at the rear of the drive, near the cables — there is a 
small label which says 'LOCK < — ► FREE'; to the right of this label as you look at the 
back of the drive is a Phillips screw. Loosen the screw and rotate the locking lever to the 
unlocked position; tighten the screw in this second hole. ALWAYS lock the rotary actua- 
tor before moving the drive. For an illustration, see the Fujitsu manual, section 2.3. 



CAUTION: Turn off the power and disconnect the power cord before opening up the Sun 
Workstation's enclosure, doing cabling of any sort, or altering peripheral/board configurations. 



7. As you stand at the rear of the drive, you'll see a small circuit board on your left-hand side. 
Make sure that the line-termination circuit board has its component-side facing away from 
you, and is securely seated into 'CNP42' on this board (*CNP42' is located next to 
*CNP4r, the 60-pin connector for the control cable). The grounding strap must be fastened 
to 'TBI' in the center of the circuit board. 'TBI' is a small silver square topped by a Phil- 
lips screw. DO NOT connect the grounding strap to 'TRMl' or •TRM2'. The line- 
termination board is required only on the /a«rdisk drive in a daisy-chain configuration. 

8. For mounting instructions, see the Fujitsu manual, section 2.4. 

9. The M2351 is connected to the card cage backpanel via two flat ribbon cables. The wider 
of the cables is a 60-pin control cable. Plug the control cable into the socket entitled 
'DISK command' on the backpanel. The narrower cable is the disk data cable, and must be 
plugged into the socket labelled 'DISK DATA #x' on the backpanel, where 2 is through 3. 
The first disk drive must be cabled to connector 'DISK DATA #0'; the second should be 
cableij to 'DISK DATA #1'. 
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Internally, the 60-pin control cable is inserted into location *CNP41' on the small circuit 
board near the left rear of the disk drive. The 25-pin data cable is inserted into location 
'CNP43' on the circuit board near the left rear of the drive. 

The disk controller installed in the card cage of both the Model lOOU and the 150U is a Xylogics 
450 controller which can control up to four drives; however, the system is configured for a max- 
imum of two drives per controller. As shipped, each drive is assumed to be the first drive, that 
is, unit number 0, by setting all sections of the drive address switch to OFF. The drive address 
switch is a 4-section DIP switch located on the small circuit board near the left rear of the 
drive. 

3.3.1. M2351 (Fujitsu 474-MByte) Disk Expansion 

If you are adding a second drive to your system, a bit of configuration work is necessary. 
Proceed as follows: 

1. Remove the terminator board from your first drive, and replace it in your new drive, mak- 
ing sure it is centered and seated securely into 'CNP42' on the second drive. 'CNP42' is 
the 60-pin connector closest to the center of the circuit board as you stand at the rear of 
the drive. The grounding strap must be fastened to 'TBI' in the center of the circuit 
board. 'TBI' is a small silver square topped by a Phillips screw. DO NOT connect the 
grounding strap to 'TRMl' or 'TRM2\ The line-termination board is required only on the 
last disk drive in a daisy-chain configuration. 

2. Set the new drive's logical address to unit number 1, by setting the first section on the 
drive address switch to ON, and leaving the other sections OFF. The drive address switch 
is a 4-8ection DIP switch located on the small circuit board near the left rear of the drive. 

3. Daisy chain the drives together using the command cable which comes with the expansion 
drive. Run this cable from the 60-pin command cable socket ('CNP41') on the drive with 
the line terminator (your expansion drive, if you followed the procedures above), to 
'CNP42' on the intermediate drive, and run this disk's command cable from 'CNP42' to the 
'DISK COMMAND' connector on the Sun backpanel. 

4. Plug the 25-pin data cables in. The first disk drive (unit ^0) must be cabled to connector 
'DISK DATA ^0'; the second (unit ^1, the expansion drive if you followed the procedures 
above) must be cabled to the 'DISK DATA #1' connector. 

No changes to the Xylogics 450 Disk Controller Board are necessary. 

Before you mount* 'chci/oi power up the drive, make sure you have followed the directions for 
removing the 'VPl^i ai!id unlocklmg the rotary actuator given in the previous section. 

3.4. Quarter- Inch Magnetic Tape 

The Sun Workstation may be shipped with a quarter-inch magnetic tape cartridge subsystem as 
part of the Fujitsu disk drive. A tape cartridge can store up to 20 Megabytes of data. 

The magnetic tape unit is controlled via a controller board manufactured by Sun Microsystems. 
The tape controller contains the hardware for managing the magnetic tape, and also contains 
256 Kbytes of memory which is accessible on the Multibus (which must be disabled if you 
are using the board with a Sun-2 CPU board). The tape controller connects to the tape 
drive via a 50-pin flat ribbon cable. The tape controller cable comes out of the back of the 
Fujitsu disk enclosure, and is labelled "TAPE". This cable plugs into the back panel connector 
labelled 'TAPE COMMAND A'. 



3-8 Revision H of 12 March 1984 



Sun 100/150 Installation Manual 



Subsystem Set-Up 



The tape cartridge is in the correct orientation when the little window with the word "SAFE" 
in it is at the top left-hand corner of the cartridge. Firmly push the cartridge into the slot in 
the front of the tape drive. It will suddenly go all the way in with a definite "click". The tape 
is now ready for use. 




To protect the tape from being written on, turn the arrow that is on the left of the window 
marked "SAFE" until the arrow points at the word "SAFE" — the tape cannot be written 
when the arrow is in this position. Turning the arrow 180 degrees so that it points away from 
the word "SAFE" allows writing on the tape. 
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3.5. Nine-Track Magnetic Tape 

The Sun Workstation may be shipped with a Control Data Streaming Tape Unit (STU) in the 

92180 family of tape drives. This tape unit is an industry-standard tape unit which can operate 

at either 25 inches per second start/stop mode, or at 100 inches per second streaming mode. 

The magnetic tape unit is controlled via a Computer Products Corporation TAPEMASTER 

tape controller. 

To unpack, mount, and cable up the nine-track magnetic tape subsystem, follow the procedures 

below. 



Note that the shipping weight of the 1/2-inch Streaming Tape Unit and its shipping carton is 
approximately 11 7 pounds. The weight of the unit itself is about 100 pounds. 



1. Cut open the top of the Streaming Tape Unit's shipping carton with a short-bladed knife 
(so as not to damage the finish on the unit). 

2. Fold back the flaps of the shipping carton to expose the inner tray, with manual and instal- 
lation kit taped on top. Remove these items. 

3. Remove the tray, and you will see the top of the unit with attached shipping frame. 

4. Have a cohort grasp one side of the frame while you grasp the other; remove the unit from 
the carton and bottom inner tray, and place it on a table top. 

We recommend that you save the salvageable shipping carton and all packing material for 
future use in case the product must be reshipped. 

5. Carefully cut and remove the non-metallic band securing the Streaming Tape Unit's door. 

6. Remove the filleji blocks which are between the upper and lower PC board rear-mounted 
hinges. 

7. Remove the door support blocks from under the door assembly. Leave the one-inch frame 
support block in place until the unit is ready for rack mounting. If you're not mounting 
the unit, simply leave the shipping frame on. 

8. Remove the filler block which is between the shipping frame and underside of the PC 
boards by carefully pressing downward on the block, and sliding it backward and out from 
under the PC boards. 

^. Remove the door stud from the installation kit. Screw the threaded end into the receptacle 
block inside the dust cover door. The tape unit will not run if the stud is not in place to 
engage the interlock switch. 

10 To mount the unit in a 19-inch rack, first bolt the two hinge assemblies and stiffener bar to 
the rack. If you're not mounting the unit, skip to step 18 for cabling instructions. 

11. Support the Streaming Tape Unit in a vertical position on the shipping frame, so that you 
can remove the four screws and detach the unit from the frame. After unmounting the 
unit, make sure your cohort is around to help you lift and maneuver it — definitely a two- 
person operation. 

12. When the frame is removcu, i^otall the two hinges on the top of the unit with the provided 
screws and lockwashers. 

13. Position the Streaming Tape Unit onto the mounting hinges. The unit must be perpendic- 
ular to the rack for the hinges to be mated. 
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14. Place the unit in a closed position. Mark the area at which the adjustable pawl fastener of 
the unit contacts the mounting rail. 

15. With the unit in an open position, install the bumper assembly into the mounting rail 
approximately one to two inches above the point at which the pawl fastener contacts the 
mounting rail. 

16. Adjust the bumper assembly so that the tape deck is parallel to the mounting rack when 
the Streaming Tape Unit is in a closed position. 

17. Place the unit in a closed position and secure it with the adjustable pawl fastener. Con- 
tinudf turning the paw! fastener clockwise until the unit is secure against the bumper assem- 
bly. 

18. The TAPEMASTER tape controller inside the Sun Workstation card cage connects to the 
tape drive via two 50-pin flat ribbon cables. Look at the back of the tape drive: there is a 
large square circuit board with two edge connectors on it. Connect the top edge connector 
("Jl") via its 50-pin ribbon cable to the socket labelled 'TAPE COMMAND A' on the back- 
panel of the card cage enclosure. Connect the bottom ("J2") edge connector via its 50-pin 
ribbon cable to the socket labelled 'DISK/TAPE COMMAND B' on the backpanel of the enclo- 
sure. 

Please read the Control Data STU Reference Manual for more information on the nine-track 
drive, tape). 
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Chapter 4 
Installing UNIX for the First Time 



This chapter describes how to install the UNIX system for the very first time on the Sun Works- 
tation. We assume that you are starting with a Sun Workstation fresh from the box, bare 
(lisk(s), and the distribution software either on a nine-track half-inch tape or on two quarter- 
inch cassette tapes. This chapter guides you through the installation procedure. 



CAUTION: If you are upgrading your Sun Model 100 or 150 rather than starting with a sys- 
tem 'fresh from the box/ please heed the warning on the front page of this manual. Sun-1 sys- 
tems which are upgrading must not attempt to install this release of the system until all Mul- 
tibus memory has been removed or disabled, and — for an upgrade from a Xylogics 440 to a 
Xy logics 450 — cabling has been re-routed. Disk drive switches may also need to be reset. 
Make sure you have followed the procedures given in Sun^s Upgrade Installation Guide before 
proceeding. 

CAUTION: If you are upgrading your system software, rather than beginning for the first 
time, read the Upgrading System Software chapter BEFORE proceeding here. The chapter gives 
procedures for saving and rebuilding your existing root and /usr file systems 



If you are installing UNIX on a machine without a tape drive, see the procedures in the next 
chapter. Installing UNIX on Systems Without Tape Support. 

We begin with a description of what is on the distribution tape. This is followed by an over- 
view of the installation procedure, including some non-trivial remarks on device abbreviations, 
what to do when you make mistakes while performing the procedure, and what facilities are and 
are not available to you during installation. Then we do a walkthrough of an actual installa- 
tion. 

4.1. What is on the Distribution Tape? 

The software needed to load the UNIX system is contained either on a 9-track magnetic tape, or 
on two quarter-inch tape cartridges, distributed with the system. The tape(s) contains eleven 
files, as follows: 
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Table 4-1: Contents of Distribution Tape(s) 



File Number Ftle Number 



A general purpose boot program which knows how to boot 

from the various devices that can be attached to the Sun 
Workstation. The PROM monitor boots this general pur- 
pose boot program. 

1 1 A copy of a program called diag. Diag is used to format 

and label disks. 

2 2 A stand alone copy program which can copy from specified 

sources to specified destinations. 

3 3 An image of a miniature version of the root file system, 

which contains enough machinery to get something up and 
running. 

4 4 Copyright file. 

5 5 The complete root file system for the UNIX operating sys- 

tem. This is on the tape in dump format and is loaded in 
by the xtr utility. 

6 A far format dump of the /usr/man (online manual 

sources), /usr/ games (games), and /usr/demo (demonstrar 
tion programs) directories. These directories are optional 
and need only be loaded onto your system if they are 
specifically required. Note that in a system which is being 
formatted for diskless users, these directories may be too 
big to fit into the public partition. You can exclude parts 
of the dump, such as demonstration programs, if you wish. 

7 7 Copyright file. 

8 Copyright file. Note that this is file 8 on the nine-track 

distribution tape; if the distribution is on a quarter-inch 
cartridge tape, this file is actually the first file on the 
second cartridge. 

9 1 An image of the /usr file system that was placed on the 

tape by the tar (I) command. The setup program transfers 
this file system to the disk. 

10 2 Copyright file. 
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4.2. Overview of the Installation Procedure 

The object of this exercise is to load the UNIX system from the magnetic tape onto the disk sub- 
system of your Sun Workstation. 



PLEASE NOTE: If you are installing a network disk server, you must have a tape drive on 
the server machine. 



The major steps in the procedure for loading the UNIX system are: 

1. If you have an Ethernet board in your system, determine network information for use 
later in installation. If you are installing a standalone workstation, you will need your 
complete Internet address (network number and host number). If you are installing a 
cluster of workstations, you will need each client*s hardware Ethernet address as well. 

2. Use the resident PROM monitor to boot the general purpose bootstrap program from the 
magnetic tape. 

3. Use the bootstrap program to load the diag utility from the magnetic tape. 

4. Format and label the disk with the diag utility. 

5. Use the bootstrap program to load the stand alone copy utility from the magnetic tape. 

0. Use the stand alone copy utility to copy the mini UNIX root file system from the tape onto 
the swap area on the disk. 

7. Boot the mini UNIX operating system from the swap area. 

8. Restore the full root file system using the xtr utility. 

9. Boot the UNIX operating system in single-user state. 

10. Run the setup program to configure your system. 

11. Boot the full UNIX system. 

12. Reconfigure the system kernel. This step is mandatory for systems with only 1 MByte of 
memory, and highly recommended for systems with more. 

13> Load the manuals, demos, and games directories if desired. 

14. Continue with network configuration and installation of utilities such as the mail system 
and tificp, configuration of a line printer, etc., by following procedures in the System Set-up 
and Operation chapter. 
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The procedures described below walk you through what you actually have to do. In all the 
examples, what you type is shown in boldface text like this. Everything shown in boldface 
should be typed exactly as it appears. Where parts of a command are shown in italic text like 
this, they refer to a variable which you have to substitute from a selection; it is up to you to 
make the proper substitution. 

Two very important variables in the examples are disk, which should be replaced with the UNIX 
device name for your disk: 

Table 4-2: UNIX Disk Device Abbreviations 



Abbreviation 



Device 



xy Xylogics 450/440 disk controller 

ip Interphase SMD-2180 disk controller 



and tape, which should be replaced with the abbreviation for your tape drive: 

Table 4-3: UNIX Tape Device Abbreviations 



Abbreviation 



Device 



mt Nine-track magnetic tape 

ar Archive quarter-inch tape 



For example, a common configuration would load from the Archive quarter^inch magnetic tape 
cartridge, onto a Fujitsu disk driven from a Xylogics 450 disk controller. In this case, tape 
would be replaced by ar (Archive tape) and disk would be replaced by xy (Xylogics disk) 
everywhere. 

If (when) you make a typijig mistake during the installation procedure, you can use the DEL 
key to erase and back up over incorrect characters you just typed. You can use the control-U 
key to kill the entire line you just typed, and start typing a new line. 

If you need to get back to the monitor for any reason, you can abort by typing 'SET-UP A' 
(hold down the SET-UP key while typing 'A') or 'ERASE-EOF A' on your workstation key- 
board at any time. On a terminal, the BREAK key generates an abort. 

During a large part of the installation procedure, you arc using the single-user UNIX system. 
Please note that the shell you are talking to in this state is the Bourne Shell, not the C Shell — 
this means that there is no history facility available. 
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4.3. Installation Walkthrough 

4.3.1. Determining Network Information 



This step is only necessary if you have an Ethernet board in your Sun system. You can skip to 
the Loading the Tape subsection just below if you don^t have Ethernet. 



4.3.1.1. Procedure for New Systems 

If you are installing a standalone workstation on a network or a cluster of networked worksta- 
tions, there are three pieces of information needed during the phase of installation which estab- 
lishes network configuration which are best obtained 'ahead of time': 

1) your network number, 

2) the hardware Ethernet address for each client, and 

3) the host number for each client. 

The Network Number 

The network number is an arbitrary value used to uniquely identify multiple networks. If 
you have been assigned a network number by ARPA use that number. If not, or if the 
entire network number business has you confused, use Sun's default network number of 
192.9.200. 

Client's Hardware Ethernet Address 

The hardware Ethernet address of each client is taken from the ID PROM on the Sun-2 
CPU Board. The address is a 6- byte hexadecimal value; each byte of the address is 
separated by a colon. A typical Ethernet address is "8:0:20:0:14:76". 

If you are installing a cluster of workstations, you will need to have each client's hardware 
Ethernet address at hand. To obtain it, power on the client's workstation. You will see the 
Sun logo, and a message like: 

Self Test completsa successfully. 

Sun Workstation, Model Sun-1/lOOU or Sun-l/150U, Sun-1 keyboard 
ROM Rev N, some_number_MB memory installed 
Serial i^8ome_number, Ethernet address 8:0:20:1 :1:A2 

Auto-boot in progress . . . 

abort by typing Ll-A or BREAK here 

Abort at tome addrett 
> 

The entire six bytes of the displayed "Ethernet address" must be used whenever you are 
prompted for the client's address; copy them down. 

Host Numbers 

Each node on a given network is uniquely identified with a host number. The size of the 
host number varies with the network number, but in all cases the host number can be from 
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1 to 254. 

During network configuration, the setup program asks if you want host numbers automati- 
cally assigned. If you answer yes, the server is given a host number of one (1) and the 
clients are assigned 2, 3, etc. This is fine if you are installing a new network with no exist- 
ing nodes attached to it. However, if you are adding workstations to an existing 
network you should assign the host numbers yourself. Remember that the host 
number must be unique across the entire network. If an existing node on the network has a 
host number of 10, do not assign 10 to a new node. 

To find the host numbers for existing nodes, take a look at the /etc/ hosts file on one of the 
existing nodes. The entries should look something like this: 



192.9.200.1 


alpha 


192.9.200.2 


beta 


192.9.200.3 


gamma 


192.9.200.4 


delta 


192.9.200.5 


epsilon 



The last component of the network address is the host number. For instance, epsilon^s host 
number is 5. 

Before beginning installation, have this address information at hand. 
4.3.1.2. Procedure for Existing Systems 

If you have an existing network (of older Suns or mixed machines) that you do not intend to 
upgrade, compatibility with a 1.1 network may need addressing. Proceed with the procedures 
given above for any machines you are installing or upgrading, and when you are finished, see 
the Making 1.1 Networks Compatible with Existing Networks section in the System Set-up and 
Operation chapter. 

4.3.2. Loading the Tape 



PLEASE NOTE: If you are installing a network disk server, you must have a tape drive on 
the server machine. 



In the case of the nine-track tape, load the tape onto the tape drive and put the drive on-line. 
In the case of a quarter-inch tape, insert the tape cartridge into the drive as described in the 
section, Quarter-Inch Magnetic Tape Subsystem in the Subsystem Set-up chapter. 

4.3.3. Loading the Bootstrap Program 

Power up the Sun Workstation (if you haven't already done so). You should see the PROM 
monitor's sign on messages. Stop the auto boot immediately by aborting — type 'SET-UP A' 
(hold down the SET-UP key while typing 'A') or 'ERASE-EOF A' on a workstation keyboard, 
or BREAK on a terminal keyboard — and then you should see the monitor's prompt, which is a 
> sign: 



4-6 Revision H of 12 March 1984 



Sun 100/150 Installation Manual Installing UNIX for the First Time 

Self Test completed successfully. 

Sun Workstation, Model Sun-1/lOOU or Sun-l/150U, Sun-1 keyboard 
ROM Rev N, some_number_MBytes memory installed 
Serial i^aomejnumber, Ethernet address n:n:n:n:n:n 

Auto- boot in progress . . . 

[ abort by typing 'SET-UP A', 'ERASE-EOF A^ or BREAK here ] 

Abort at some addresa 
> 

You boot the general purpose bootstrap program from the tape by typing a b (for boot) com- 
mand to the monitor. The monitor echoes the boot command back to you, with the parameters 
filled in. A default boot command looks like this: 

> b tape{) 
Boot: (ape (0,0,0) 

Remember: tape here should be replaced by mt for the nine-track tape, or ar for the Archive 
quarter-inch tape. 

The bootstrap program displays a sign on message, and then displays a prompt sign of Boot: to 
indicate that it is ready to accept commands. Whenever the bootstrap program is ready for a 
command, it displays the Boot: sign at the start of the line. So, the initial dialogue with the 
monitor and the bootstrap program would look like this: 

> b tape{) 
Boot: f ape (0,0,0) 

Boot: 

Now the standalone boot program is in control. All programs that it loads in eventually return 
control to it. When the bootstrap program loads another program, it displays some numbers 
which are the sizes of the different portions of the program it loaded. 

4.3.4. Using the Diag Utility 

Next, you use diag (the interactive disk format utility) to format and label your disk(s). diag 
has two 'phases ^ in the first, it prompts for information about the type of disk drive and con- 
troller it is working with, and essentially 'configures' itself to work with that disk and con- 
troller; and in the second, it responds to commands like the format and /a6e/ commands we use 
during this installation phase. If you have multiple drives/controllers, go all the way through 
the format and labelling phase for the first drive on your first controller, and then loop back to 
begin the cycle for your next device — we give directions for this at the appropriate time. 

You boot diag from tape by typing a bootstrap command like this: 
Boot: tape{0,0,l) 

where tape is replaced with mt for the nine-track tape, or ar for the Archive quarter-inch tape. 
The bootstrap program should boot diag from the magnetic tape. When diag starts up, it 
displays a sign on message: 
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Disk Initialization and Diagnosis 

When asked if you are sure, respond with 'y' or 'Y' 

Diag first asks you a series of questions about the disk you will be using. The answers to these 
questions ^configure* diag to work with that specific hardware. The first thing diag wants to 
know is the type of disk controller to use: 

specify controller: 

- Interphase SMD-2180 

1 - Xylogics 440 (prom set 926) 

2 - Xylogics 450 

3 - Adaptec ACB 4000 - SCSI 
which one? 2 

In this example, we specified that the controller is type 2 for a Xylogics 450 SMD controller. 

Diag's next question is what address this controller occupies on the Multibus. When you give 
diag the address (see table below )^, it echoes the address back to you: 

Specify controller address on the Multibus (in hex): select the address from the table below 

Device address: whatever address you selected 

The table below shows the default addresses for disk controllers. 

Table 4-4: Default Addresses for Disk Controllers 



Address (hex) 
Controller Type 

1st Controller 2nd Controller 



Interphase SMD-2180 40 48 

Xylogics 450/440 ee40 ee48 



Next, diag wants to know the unit number of the disk: 
Which unit? 

"0" is the correct response for the first drive on the controller specified above. "1" is the unit 
number for the second drive on a controller, and so on. 

Now diag wants to know the type of disk drive you are working with. Diag displays a menu of 
the di£ferent disks. When you have specified which disk drive you wish to operate on, diag 
displays a table of the physical data about that disk, which includes the number of cylinders, 
number of alternate cylinders, number of heads, and number of sectors per track. In this exam- 
ple, we are formatting the Fujitsu M2312K (Sun "D84") 84-MByte disk: 



2 Note that if you have one Xylogics SMD Controller and one Interphase Controller in your sys- 
tem, you cannot use the default addresses (as the Interphase Controller sees only four bytes). The 
Interphase must be configured to be at address 48, and the Xylogics at ee40. See the Hardware 
Configuration and Expan$ion chapter for board configuration procedures. 
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Specify drive: 

- Fujitsu-M2312K (Sun D84) 

1 - Fujitsu-M2284 (Sun D169) 

2 - Fujitsu-M2351 Eagle (Sun D474) 

3 - Fujitsu-M2294 

4 - CDC- Lark- cartridge 

5 - CDC-Lark-fixed 

6 - CDC-Larkll-cartridge 

7 - CDC-Larkll-fixed 

8 - CDC-9766 

9 - CDC-9730-160 

10 - CDC-9730-80 

11 - CDC-9730-24 

12 - CDC-9730-12 

13 - Ampex-Scorpio 

14 - Am pex- Capricorn 

15 - Other 

which one! 

ncyl 586 acyl 3 nhead 7 nsect 32 interleave 1 

status: 

drive status ready 

At this point, diag knows all it needs to know about the disk, and it displays its 'second phase' 
prompt: 

diag> 

One of the responses to this prompt can be the h (for help) command. If you use the h com- 
mand, diag displays a list of its commands. 

4.3.4.1. Formatting the Disk 

Next, you use diag^s disk formatting function. Begin by clearing any outstanding errors (espe- 
cially important if you are using an Interphase disk controller) with the clear command: 

diag> clear 

clear 

diag> 

Now, type the format command. Diag warns you that formatting a disk destroys all informa- 
tion which might already be stored on that disk, and asks for confirmation before going ahead 
and doing the job: 

diag> format 

format/verify, DESTROYS ALL DISK DATA! 

are you sure? y 

if' of surface analysis passes ? 5 

When formatting a disk for the first time, five surface analysis passes is a reasonable number. 
The surface analysis phase of the formatting is for detecting bad spots on the disk and mapping 
them to alternate places. The format phase takes about 30 minutes for one surface analysis 
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pass on an 84-MByte disk, using an Interphase SMD-2180 disk controller, and slightly less time 
using a Xylogics 450 or 440 controller. It is well worth taking the time to do this when format- 
ting a new disk. Diag then formats the disk, and displays the current cylinder number as it for- 
mats each cylinder. You can use just one surface analysis pass if you are reformatting a disk 
that has been formatted before, and is known not to have any bad spots. 

At the end of the format process, diag displays a message telling you that it has finished, then 
tells you to use the label command to label the disk: 

cyl 588 format complete - bad sector(s) 
Use the label command to label the disk 
diag> 

This is the next step. 

4.3.4.2. Labelling the Disk 

A disk must be labelled after it has been formatted. The purpose of a label is to record (in a 
well known place on the disk) information about how the disk is divided into partitions for 
different purposes such as paging space and file systems. 

Diag labels a disk in response to the label command. Mere is an example of using label to write 
a label on the disk which was formatted in the discussion above. When you give the command 
to diag, it asks if you want to use the logical partition map that is 'built in' to the program: 

diag> label 

label this disk... 

OK to use logical partition map 'Fujitsu-M2312K (Sun D84)' ? y 

Are you sure you want to write? y 

Then, when diag has labelled the disk, it verifies the label it has just written. There is in fact a 
separate verify command, but diag automatically does a verify as part of the labelling process: 

verify label 

id: <Fujitsu-M2312K cyl 586 alt 3 hd 7 sec 32 > 

Partition a: starting cyl:=0, ^ blocks=15884 [ ^s vary with disk controller ] 

Partition b: starting cyl»d7, # blocks— 33440 

Partition c: starting cyl««0, # blocks»131264 

Partition g: starting cyl— 208, # blocks'>"817d0 
diag> 

This is the end of the disk formatting and labelling process. If you have a second 
drive/controller, you now get back to the beginning of diag^s first phase by responding to diag^s 
prompt with the diag command: 

diag> diag 

If you have only one disk on your controller, or if you are done formatting and labelling all of 
your disks, you are ready to continue with the next phase of installation. Get back to the 
bootstrap program by typing the q (quit) command, and the bootstrap displays its prompt sign 
again: 

diag> q 

Boot: 
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4.3.5. Loading the Mini UNIX System 

After your disk(s) are formatted and labelled, the next job is to load in the mini UNIX root file 
system from the tape. This is done by loading in the standalone copy program which is the 
third file (#2) on the tape(s). The copy program prompts you for the source and destination of 
the copy, as shown here. (As always, the example assumes that tape stands for a tape device — 
such as — and that disk stands for a disk device — such as xy for the Xylogics disk controller, 
or ip for the Interphase disk controller): 

Bpot: f ape (0,0,2) 

20480+ 4096+ 113384 bytes [ #s vary with system level ] 

Standalone Copy 

From: f ape (0,0,3) 

To: ditk{0,0,l) 

Note that after you have typed in the tape information for the 'From' prompt, the copy pro- 
gram moves the tape for about ten seconds before displaying the *To' question. Copying in the 
mini-UNIX system takes about three minutes, using a half-inch tape, and about six minutes, 
using a quarter-inch cartridge. At the end of the copy, the copy program returns control to the 
bootstrap program: 

Copy completed 

Boot: 



4.3.6. Booting the Mini UNIX System 

Next, you tell the bootstrap program to boot the mini-UNIX system from the disk. Because this 
mini-UNIX system boot is an unusual one, you must specify the —a (for ask me) option on the 
boot command, and also the — s (come up single user) option, as follows: 

Boot: (/t«A; (0,0,1 )yinu nix -as 

243712+ 30720+ 49768 start 0x4000 [ #s vary with system level ] 

[ . . . about a dozen lines of configuration messages . . . ] 

The mini-UNIX system displays some messages about the configuration of the system on which it 
is running, and finally displays a message asking for its root file system. The root file system at 
this stage is ^^di8k0*^\ which has a special meaning to the small UNIX system. Since this nota- 
tion looks ambiguous, let me specify: if you have a Xylogics disk controller, your root device is 
xyO* ; if you have an Interphase controller, it is ipO* — the asterisk is part of the device name: 

root device? diskO* 

At this point the system may gently remind you to reset the system date and time: 
WARNING: clock gained 16845 days - CHECK AND RESET THE DATE! 
You can do this when your prompt returns, with the date{l) command. 
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4.3.7. Setting the Date 

Now the mini-UNDC system starts up and displays its prompt sign: a ^ character. Set the 
correct system date and time by using date{l): 

# date yymmddhkmml.ia] 

yy here is the last two digits of the year; mm specifies month; dd designates day of the month; 
hh is hour (on a 24-hour clock); the next mm is minutes elapsed; and the optional .»» specifies 
seconds. The system echoes the date set back to you. 

4.3.8. Loading the Root File System 

Next, tell the mini-UNIX system to extract the real root file system from the tape with the fol- 
lowing sequence: 

# d isc^ rft« A; t ape=f ape xtr 

Replace disk with xy for the Xy logics disk controller, or ip for the Interphase disk controller. 
Replace tapt with mt for the nine-track tape, or ar for the Archive quarter-inch tape. The xtr 
command is a shell script which creates a root file system and extracts it from the tape. The 
xtr shell script displays a lot of messages which look something like this: 
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# diBC^sdisk tapes=:f ape xtr 

+ cd /dev 

-t- ./MAKEDEV ditkO tapeO 

I Possible messages from MAKEDEV ] 

+ echo /dev/(/t«A;Oa:/a:xx:l:l 

+ sync 

+ /etc/newfs /dey/rdiskO^ 

Warning: 20 sector(s) in last cylinder unallocated 

/dev/rrfi»A:Oa: 15884 sectors in 71 cylinders of 7 tracks, 32 sectors 

8.1Mb in 5 cyl groups (16 c/g, 1.84Mb/g, 672 i/g) 
super-block backups (for fsck -b#) at: 

32, 3648, 7264, 10880, 14496, 
+ sync 

+ /etc/fsck /dey/rdiakOs, 
*♦ /dcv/rrfi«*Oa 

[ . . . Informative messages from fsck . . . ] 

+ /etc/mount /dev/rfi«A;Oa /a 

+ mt -f /dev/rtapcO re^ 

+ cd /a 

+ /etc/restore rsf 6 /dev/rtapeO 

[ . . . Restoring the file system takes about six minutes with 
a 1/2- inch tape, and fifteen with a 1/4-inch cartridge . . . ] 

+ rm -f / a/rest oresymt able 

4- cd /a/dev 

+ ./MAKEDEV std diskO tapeO ptyO winO 

+ cd / 

+ /ctc/umount /dev/rfi«A;Oa 

+ sync 

+ /etc/fsck /dev/rdiskOdk 

** /dev/rrfwibOa 

[ . . . Informative messages from fsck . . . ] 

+ echo Root filesystem extracted 
Root filesystem extracted 

# 

At this point, the UNIX system has a complete root file system. There is as yet no /usr file sys- 
tem, and that is part of the next job. 

4.3.9. Booting the UNIX System 

Now you must escape back to the monitor by typing 'SET-UP A' (hold down the SET-UP key 
while typing *A') or 'ERASE-EOF A' on a workstation keyboard, or BREAK if you are using a 
terminal. The monitor responds by displaying a message to the effect: 

Abort at some address 
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When you see the monitor > sign, you boot the UNIX system by typing a b command to the 
monitor, and the monitor responds by filling in the full details of the boot command. We must 
boot the UNIX system with the -s option (come up single user), because there is no tur file sys- 
tem as yet: 

> b vmunix — s 

Boot: <fi«/;(0,0,0)vmunix -s 

Load: (/t«A; (0,0,0 )boot 

The UNIX system startup procedure is automatic. It displays a progress report as it goes 
through the initialization sequence. 

Boot: (/t«A;(0,0,0)ymunix 

219136+ 28672+ 29088 

Sun UNIX 4.2 (GENERIC) #145: Tue Feb 21 20:35:13 PDT 1984 

Copyright (c) 1984 by Sun Microsystems, Inc. 

[ . . . Several lines of configuration messages . . . ] 
# 



4.3.10. Using Setup to Configure Your System 

At this point you invoke the setup program to configure your system. 

Setup is essentially a system configurator in two parts: it consists of an interactive front-end 
which gathers the information necessary to configure your system by conducting a dialogue with 
you, and a non-interactive back-end which uses this information to do the actual configuration. 
During the dialogue, setup does consistency and error checking to ensure that the configuration 
will work. If errors are detected, they are reported to you, and you are asked to enter corrected 
information. 

You will use a different setup path if you are configuring 

• A standalone system, 

• A network server with equal-sized client partitions, or 

• A network server with different-sized client partitions. 

If you are configuring a standalone system, the dialogue with setup is fairly straightforward. 
Glance through the next section. Path 1: Standalone System Configuration , to familiarize your- 
self with the program ^s conventions. 

If you are configuring a network server with one or more diskless nodes ("clients"), you can 
establish equal or unequal client partitions. The choice depends in part on your clients* storage 
needs — do they vary or are they roughly equivalent? — and also on your available resources — 
you may need to allocate unequal partitioning to accommodate all clients, for example. Please 
read the following before making the decision, as it is extremely difficult to *undo' an esta- 
blished configuration. 

This release of the system runs diskless workstations off one or more server disks by keeping a 
read-only copy of common files in the /pub directory (partition) of one of your drives. On this 
drive, the server machine uses partition 'a* as its root and partition 'b' as its paging area. The 
remainder of the drive (partition *g') contains the /pub filesystem, followed by 'subpartitions' for 
the diskless clients. Each diskless client machine is allocated a file system area for private disk 
storage and a paging area (see nd{4) to understand how this is done). A generic abstract disk 
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would thus look something like this: 

Table 4-5: Layout of a Generic Abstract Disk 



Ueer Minimum (MBytes) Default (MByte*) 


a 


Server's root 


7.7 


7.7 


b 


Server's paging area 


16.3 


16.3 


g 


Ipuh 


17.0 


20.0 


Client I's file system area 


x.O 


x.O 


Client I's paging area 


4.0 


6.0 


Client 2's file system area 


x.O 


x.O 


Client 2's paging area 


4.0 


6.0 



Partitions *a' and 'b' were sized during the disk-labelling phase of diag, above; they are 7.7 and 
16.3 MBytes respectively. The minimum configuration provided by setup then allocates 17 
MBytes for I pub, 4 MBytes for each client's paging area, and then equally subdivides the 
remaining disk space for each client's file system. These minimum values are bare minimums; 
we suggest using them only if you have to (for example, to fit two clients on an 84-MByte disk). 
The default values noted above are much more livable partition sizes. 

If you want to include the files containing the online manual pages, demos, or games, the public 
partition must be increased by the following amounts: 

Table 4-6: Increase in J pub Size to Accommodate Online Maitt!3,] Pages, Demos, or Games 



Manual Pages 


2.1 MBytes 


Demos 


3.75 MBytes 


Games 


1.8 MBytes 



If you want to allocate equal amounts of disk space to each client, read through the subsection. 
Path 2: Standard Server Configuration. This path allows you to select the size of the public 
partition, and a size for a standard paging partition which will be given to each client. The 
remaining disk space will be divided equally among the clients as their file system area. Note 
that if you use this path, you must put /pub on the first disk you configure. 

To assign different amounts of disk space to clients, read through the subsection, Path 3: Non- 
standard Server Configuration . This path allows you to select the size of the public partition, 
each client's paging area, and each client's file system area. This path also allows you to put 
/pub on a disk other than your first disk configured. Since the path for establishing a non- 
standard system configuration is slightly more complex than the other two paths, it requires 
some pre-planning. We have therefore included two copies of a worksheet which will help you 
consolidate the information you need before using setup, as well as one sample completed 
worksheet to use as a guide. PLEASE complete the worksheet before attempting configuration. 
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4.3.10.1. Path 1: Standalone System Configuration 

This subsection provides an example of the setup interactive dialogue which is typical for a 
standalone workstation. In the example, what you might type in is shown in boldface type 
like this; whatever is simply displayed on the workstation monitor is shown in Roman type 
like this. 

We invoke the setup program by typing the setup command. Setup begins by requesting global 
information: 

# setup 

Sun Microsystems Configuration System 

Global Information 

1) network disk server 

2) standalone 

3) standalone with remote tape 

Enter the number for your environment: 2 

You have a standalone system; is this correct? (y/n): y 

Note that the setup program asks you to verify configuration information after each 'phase' of 
configuration is complete. It is extremely difficult to undo system configuration, so be careful 
with your responses: 'y' casts things in concrete, and 'n' allows you to start the phase over 
again. You can also type 'q' to any prompt to quit the setup program and return to the shell — 
this allows you to annihilate what you have done and start over, if you have to. 

Next, setup establishes your workstation's identity: name and — if you are tied into a network 
— address: 
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Host Information 

Enter your hostname: lucifer 

Is this workstation on a network? (y/n): y 

Network numbers may be either class A, B or C 
Their formats are: 

Class A: nnn ( <= nnn <= 127) 

Class B: nnn.bl (128 <= nnn <= 191) 
Class C: nnn.bl.b2 (192 <= nnn <= 255) 

bl and b2 are one byte (0-255) quantites 

Enter your network number (default is 192.9.200): <RETURN> 

Your network number is 192.9.200; is this correct? (y/n): y 

Enter your host number 

This is a number between 1 and 255: 14 

Your hostname and host number are: 

lucifer: 14 

Is this correct? (y/n): y 

Note that you need your network and host numbers here if your machine is on a network (see 
the earlier section, Determining Network Information, for an explanation of network and host 
numbers). Make sure you have these at hand before starting the dialogue. 

The last phase of setup configuration requests information about your tape subsystem: 
Tape Information 

1) 1/4" SCSI tape (st) 

2) 1/2" magnetic tape (mt) 

3) 1/4" archive tape (ar) 

Enter the number for the type of tape: (1-3): 3 

You have specified a 1/4" archive tape; is this correct? (y/n): y 

When this last phase has been completed, setup asks you whether you want to institute the 
configuration you have designed and, if you confirm, proceeds to edit several of the database 
files: 

You have completed the configuration questions. 
Continuing will destroy any existing files under /usr 
and any client partitions if you are a server. 

Do you want to begin configuration? (y/n): y 

Updating /etc/hosts 

[ . . . A few lines of configuration messages . . . ] 

If your distribution is on two 1/4-inch tape cartridges, setup will prompt you to change to the 
second cartridge about two minutes into its back-end routine. Insert the second tape and type 
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'RETURN' to continue the routine; it takes approximately 25 minutes to complete. When 
setup completes its back-end work, your shell prompt returns. You can then continue your 
installation by booting the full UNIX system, as described near the end of this chapter. 

4.3.10.2. Path 2: Standard Server Configuration 



Note that if you follow this path, you are constrained to put /pub on the first disk you 
configure. 



This subsection provides an example of the setup interactive dialogue which is typical for a 
standard network server configuration. This path allows you to select the size of your public 
partition, and establish the size of a standard paging partition which is allotted to each client. 
The remaining disk space is equally divided to make each client's file system subpartition. 

In the example, what you might type in is shown in boldface type like this ; whatever is sim- 
ply displayed on the monitor is shown in Roman type like this. 

We invoke the setup program by typing the setup command. Setup begins by requesting global 
information: 

^ setup 

Sun Microsystems Configuration System 

Global Information 

1) network disk server 

2) standalone 

3) standalone with remote tape 

Enter the number for your environment: 1 

You have a network disk server system; is this correct? (y/n): y 

Note that the setup program asks you to verify configuration information after each 'phase' of 
configuration is complete. It is extremely difficult to undo system configuration, so be careful 
with your responses: 'y' casts things in concrete, and 'n' allows you to start the phase over 
again. You can also type 'q' to any prompt to quit the setup program and return to the shell — 
this allows you to annihilate what you have done and start over, if you have to. 

After determining your environment, setup gathers information about your disk configuration. 
It determines the type of disk controller being used for installation, and asks you for device 
information: 

You have booted oflf of a Xylogics disk controller 

Enter the number of disks attached to the Xylogics controller: (1-2): 2 

The Xylogics disk controller has 2 disk(s): 
xyO 
xyl 

Is this configuration correct? (y/n): y 
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For the remainder of the dialogue, setup will refer to your disk(s) by their UNIX device abbrevia- 
tions. Next, setup begins the partitioning process for the first-named disk. If your configuration 
includes more than one disk on a single controller, as in our example, setup will completely 
finish partitioning the first disk and then turn to the second. If you have multiple controllers, 
you will be asked to repeat this entire phase for each controller. Your configuration will be vali- 
dated after all disks have been partitioned. If errors are found at that time — for example, if all 
clients have not been allocated both file system and paging areas — you will be asked to edit 
your specified configuration until it is correct. 

The partitioning phase of the dialogue with setup looks like this: 
Disk Partition Information 
Would you like to partition device xyO into "n" equal sized clients? (y/n): y 

Enter the pub partition size (nnnM or nnnK) 

- minimum is 17408K 

- default is 20480K: 17M 
Partition size rounded to 17472K. 

Enter the swap partition size (nnnM or nnnK) 

- minimum is 4096K 

- default is 6144K: 8M 
Partition size rounded to 8288K. 

Enter the number of clients on device xyO: (1-3): 2 

Enter a client's name: adam 

Ff^ter a client's name: eve 

You are asked to declare partition sizes in K Bytes or M Bytes, and setup takes care of rounding 
your partitions to cylinder boundaries for performance reasons. You can always type 
'RETURN' as a response to a sizing prompt to get the default partitioning. 

This partitioning phase of the dialogue sets up a /pub partition of whatever size you select (if 
this is the first device being partitioned), allocates a standard paging area for each of your 
specified clients (again, you determine the size), and carves the remaining free disk space into 
equally sized user subpartitions for each of them. 

This completes partitioning for the first disk. If you have another controller, you are asked for 
its type, and the number of devices attached to it at this time, and are then asked to repeat the 
partitioning process for each disk. When all disks have been partitioned, setup asks for network 
information for each of your specified clients and your network server: 
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Network Information 

Network numbers may be either class A, B or C 
Their formats are: 

Class A: nnn (000 <= nnn <= 127) 

Class B: nnn.bl (128 <= nnn <= 191) 

Class C: nnn.bl.b2 (192 <= nnn <= 255) 

bl and b2 are one byte (0-255) quant ites 

Enter your network number (default is 192.9.200): <RETURN> 

Your network number is 192.9.200; is this correct? (y/n): y 

Enter the 6- byte hexadecimal ethernet address for each of the clients 
The correct form is xx:xx:xx:xx:xx:xx 

Client adam: 8:0:20:0:14:76 

Client eve: 8:0:20:0:8:14 

The clients and their ethernet addresses are: 

1) adam: 8:0:20:0:14:76 

2) eve: 8:0:20:0:8:14 

Are the ethernet addresses correct? (y/n): y 

Do you want host numbers automatically assigned? (y/n): y 

Server Information 

Enter the name of the server: sun 

The server's hostname is: 

sun 
Is this correct? (y/n): y 

Note that you use your network number, and your clients' hardware Ethernet addresses (estar 
blished at the outset of the installation procedure) here. You may assign host numbers yourself, 
or have setup assign them automatically. For a discussion of network and host numbers, and 
clients' hexadecimal Ethernet addresses, see the earlier section, Determining Network Informa- 
tion. 

The last phase of setup configuration requests information about your tape subsystem: 
Tape Information 

1) 1/4" SCSI tape (st) 

2) 1/2" magnetic tape (mt) 

3) 1/4" archive tape (ar) 

Enter the number for the type of tape: (1-3): 3 

You have specified a 1/4" archive tape; is this correct? (y/n): y 

When this last phase has been completed, setup asks you whether you want to institute the 
configuration you have designed and, if you confirm, proceeds to edit several of the database 
files: 
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You have completed the configuration questions. 
Continuing will destroy any existing files under /usr 
and any client partitions if you are a server. 

Do you want to begin configuration? (y/n): y 

Updating /etc/hosts 

[ . . . A few lines of configuration messages . . . ) 

If your distribution is on two 1/4-inch tape cartridges, setup will prompt you to change to the 
second cartridge about two minutes into its back-end routine. Insert the second tape and type 
'RETURN' to continue the routine; it takes approximately 25 minutes to complete. When 
setup completes its back-end work, your shell prompt returns. You can then continue your 
installation by booting the full UNIX system, as described below. 

4.3.10.3. Path 3: Non- Standard Server Configuration 



Note that if you follow this path, you need not put /pub on the first disk you configure, as you 
must in Path 2. 



4.3.10.3.1. Configuration Worksheet for Path 3 

The purpose of this worksheet is to allow you to gather and stabilize your system configuration 
before you cast it in concrete with the setup program. Basically the worksheet helps you deter- 
mine your real storage resources, the number of users you want to support, how you want to 
allocate your free disk space, and certain items of network configuration information necessary 
for the setup dialogue. We have provided two copies of the worksheet so that you can draft and 
redraft if necessary; it will be to your advantage to write everything out. We have also pro- 
vided a sample completed worksheet to use as a guide. 

There are several things to keep in mind during this process. One important point is that once 
the disk has been divided up in a certain way, it is extremely difificult to alter that structure. It 
can be changed only by going through the entire first time installation procedure again. There- 
fore, you might give some thought to what your future requirements are before you complete 
the worksheet. For example, you may want to "reserve" a client or two for future diskless sta- 
tions that will be added in the coming months. The storage that you allocate for those future 
clients does not have to remain unused. You can make such partitions available as extra 
mounted filesystems for the original set of clients. 

Now simply fill in tne blanks. 
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Example Worksheet 



The following is a sample worksheet for a configuration of 1 file server and 3 clients with 2 84- 
MByte (unformatted) disks. Each client has different disk space needs, so the disk space has 
been allocated accordingly. 



Network Number: 192.9.200 



User 


User Name 


User Space 


Paging Space 


Hoatnxtmber 


Ethernet Address 


Server 


dad 


7.70MBytes 


16.3MBytes 


32 


Not Needed 


Client 1 


robbie 


SO.OMBytes 


IS.OMBytes 


33 


8:0:20:31:41:59 


Client 2 


chip 


20.0MBytes 


lO.OMBytes 


34 


8:0:20:27:18:28 


Client 3 


ernie 


15.0MBytes 


e.OMBytes 


35 


8:0:20:6:02:25 


Client 4 












Client 5 













7.7 



24 



49 



59 



65 



Disk #0 



Server's User 



Server's Paging 



/pub 
(games, demos, man) 



Ernie's User 



Ernie's Paging 



7.7 



16.3 



25 



10 






Disk # 1 


30 


Robbie's User 


40 


Robbie's Paging 


45 


Chip's User 


65 


Chip's Paging 



30 



10 



15 



10 
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Sample Worksheet #1 



1 . Number of disks and size (MBytes) of each disk: 



First Controller 


Disk Unit 


Size 


#0 




#1 





Second Controller 


Disk Unit 


Size 


#0 




#1 





The following table shows approximate free space for allocating client file system, client pag- 
ing, and I pub subpartitions for Sun-supplied disk subsystems. The numbers are approxi- 
mate because formatted capacity depends on the type of controller being used with the 
drive, Use the table to determine your real total storage resources. 



Available Disk Space 


Disk 


Raw 


Formatted 


With Server 


Fujitsu SMD 8-inch 


84 MBytes 


65 MBytes 


40 MBytes 


Fujitsu SMD 14-inch 


169 MBytes 


133 MBytes 


106 MBytes 


Fujitsu Eagle 


474 MBytes 


384 MBytes 


359 MBytes 



2. On the next page, allocate partitioning, complete network information, and block out ^real 
resource' disks. 

When you allocate partitioning, remembe? 

• to include the /pub partition with the clients for disk units with /pub partitions. 

• that setup^s minimum values for client subpartitions are 4 MBytes file system area + 4 
MBytes paging area = 8 MBytes per client. You must use these minimums to accomo- 
date 2 clients on an 84-MByte (unformatted) disk. Default values — to give you more liv- 
able figures — are 6 MBytes file system area -f 6 MBytes paging area = 12 MBytes per 
client. 

• that the /pub partition must be at least 17 MBytes (for a /pub without manual pages, 
demos, or games); 20 MBytes is the default. If you wish to include the manual pages, 
demos, and games, allow 2.1 MBytes, 3.75 MBytes, and 1.8 MBytes respectively. 

• that the server's root and server's paging partitions are allocated automatically by diag, 
and are 7.7 MBytes and 16.3 MBytes respectively for SMD disks. 

• that setup rounds partitions to cylinder boundaries which vary depending on controller 
type and disk size, so these numbers are approximate — variance will be about ± 5%. 
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Network Number: 



User 


User Name 


User Space 


Paging Space 


Hostnumber 


Ethernet Address 


Server 




7.7MBytes 


16.3MBytes 






Client 1 












Client 2 












Client 3 












Client 4 












Client 5 













Total 




7.7 



24.0 



Disk #0 



Server's User 



Server's Paging 



Partition 



7.7 



16.3 



Total 




Partition 
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Sample Worksheet #2 



1. Number of disks and size (MBytes) of each disk: 



First Controller 


Disk Unit 


Size 


#0 




#1 





Second Controller 


Disk Unit 


Size 


#0 




#1 





The following table shows approximate free space for allocating client file system, client pag- 
ing, and I pub subpartitions for Sun-supplied disk subsystems. The numbers are approxi- 
mate because formatted capaicity depends on the type of controller being used with the 
drive. Use the table to determine your real total storage resources. 



Available Disk Space 


Disk 


Raw 


Formatted 


With Server 


Fujitsu SMD 8-inch 


84 MBytes 


65 MBytes 


40 MBytes 


Fujitsu SMD 14-inch 


169 MBytes 


133 MBytes 


106 MBytes 


Fujitsu Eagle 


474 MBytes 


384 MBytes 


359 MBytes 



2. On the next page, allocate partitioning, complete network information, and block out ^real 
resource' disks. 

When you allocate partitioning, remembfch 

• to include the I pub partition with the clients for disk units with /pub partitions. 

• that setup^s minimum values for client subpartitions are 4 MBytes file system area + 4 
MBytes paging area = 8 MBytes per client. You must use these minimums to accomo- 
date 2 clients on an 84-MByte (unformatted) disk. Default values — to give you more liv- 
able figures — are 6 MBytes file system area + 6 MBytes paging area =12 MBytes per 
client. 

• that the /pub partition must be at least 17 MBytes (for a /pub without manual pages, 
demos, or games); 20 MBytes is the default. If you wish to include the manual pages, 
demos, and games, allow 2.1 MBjrtes, 3.75 MBjrtes, and 1.8 MBytes respectively. 

• that the server's root and server's paging partitions are allocated automatically by diag, 
and are 7.7 MBytes and 16.3 MBytes respectively. 

• that setup rounds partitions to cylinder boundaries which vary depending on controller 
type and disk size, so these numbers are approximate — variance will be about dt 5%. 



Revision H of 12 March 1984 



4-25 



Installing UNIX for the First Time 



Sun 100/150 Installation Manual 



Network Number: 



User 


User Name 


User Space 


Paging Space 


Hostnumher 


Ethernet Address 


Server 




7.7MBytes 


16.3MBytes 






Client 1 












Client 2 












Client 3 












Client 4 












Client 5 













Total 




7.7 



24.0 



Disk #0 



Server's User 



Server's Paging 



Partition 



7.7 



16.3 



Total 




Partition 
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4.3.10.3.2. Setup Walkthrough for Path 3 

This subsection provides an example of the setup interactive dialogue which is typical for the 
non-standard network server configuration. This path allows you to select the size and disk 
placement of the public partition, the size of each user^s paging partition, and the size of each 
user's file system area. In the example, what you might type in is shown in boldface type like 
this; whatever is simply displayed on the monitor is shown in Roman type like this. 

We invoke the setup program by typing the setup command. Setup begins by requesting global 
information: 

# setup 

Sun Microsystems Configuration System 

Global Information 

1) network disk server 

2) standalone 

3) standalone with remote tape 

Enter the number for your environment: 1 

You have a network disk server system; is this correct? (y/n): y 

Note that the program asks you to verify configuration information after each *phase' of 
configuration is complete. It is extremely difficult to undo system configuration, so be careful 
with your responses: 'y' casts things in concrete, and 'n' allows you to start the phase over 
again. You can also type 'q' to any prompt to quit the setup program and return to the shell — 
this allows you to annihilate what you have done and start over, if you have to. 

After determining your environment, setup gathers information about your disk configuration. 
It determines the type of disk controller being used for installation, and asks you for device 
information: 

You have booted off of a Xylogics disk controller 

Enter the number of disks attached to the Xylogics controller: (1-2): 2 

The Xylogics disk controller has 2 disk(s): 
xyO 
xyl 

Is this configuration correct? (y/n): y 

For the remainder of the dialogue, setup will refer to your disk(s) by their UNIX device abbrevia- 
tions. Next, setup begins the partitioning process for the first-named disk. If your configuration 
includes more than one disk on a single controller, as in our example, setup will completely 
finish partitioning the first disk and then turn to the second. If you have multiple controllers, 
you will be asked to repeat this entire phase for each controller. Your configuration will be vali- 
dated after all disks have been partitioned. If errors are found at that time — for example, if all 
clients have not been allocated both /usr and paging areas — you will be asked to edit your 
specified configuration until it is correct. 

The partitioning phase of the dialogue begins with an opportunity to allocate equal partitioning 
(Path 2); this is followed by optional allocation of the /pub subpartition: 
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Disk Partition Information 

Would you like to partition device xyO into "n'* equal sized clients? (y/n): n 

Partitions for disk xyO - 40880K bytes free 

Do you want the public partition on this disk unit! (y/n): y 

Enter the pub partition size (nnnM or nnnK) 

- minimum is 17408K 

- default is 20480K: 17M 
Partition size rounded to 17472K. 

Throughout this phase, setup declares the amount of free space on your disk and lists any allo- 
cated partitions before asking you to alter the partitioning in any way. You are asked to 
declare partition sizes in K Bytes or M Bytes, and setup takes care of rounding your partitions 
to cylinder boundaries for performance reasons. You can always type 'RETURN' as a response 
to a sizing prompt to get the default partitioning. 

The next step in partitioning is to allocate client /usr and paging areas (which need not be on 
the same disk, although each client must have both). If you want to 'reserve' space for future 
users, allocate "other" partitions of appropriate size: 

Partitions for disk xyO - 23408K bytes free 
1) public: 17472K 

Do you want to add or edit a partition? (y/n/1): y 

Enter the partition type (user/swap/other): user 

Enter the user partition size (nnnM or nnnK) 

- minimum is 4096K 

- default is 6144K: 8M 
Partition size rounded to 8288K. 

Enter the name of the client: Blaise 

Continue this process until you have finished partitioning your first disk. Setup then allocates 
any remaining disk space to "other", and asks you to verify your work. If something has gone 
wrong, you can edit a partition by responding with its number when you are prompted for 
adding or editing. Both size and type fields can be changed. Our final screen might look some- 
thing like this: 



Partitions for ( 


iisk xyO • 


• OK bytes free 


1) public - 




17472K 


2) blaise's 


user; 


6272K 


3) blaise's 


swap: 


4256K 


4) albert's 


user: 


6272K 


5) albert's 


swap: 


4256K 


6) other: 




2352K 



Is this partitioning correct? (y/n): y 

This completes partitioning for the first disk. If you have another controller, you are asked for 
its type, and the number of devices attached to it at this time, and are then asked to repeat the 
partitioning process for each disk. When all disks have been partitioned, and the configuration 
has been validated, setup asks for network information for each of your specified clients and 
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your network server: 

Network Information 

Network numbers may be either class A, B or C 
Their formats are: 

Class A: nnn (000 <= nnn <= 127) 

Class B: nnn.bl (128 <= nnn <= 191) 
Class C: nnn.bl.b2 (192 <= nnn <= 255) 

bl and b2 are one byte (0-255) quantites 

Enter your network number (default is 192.9.200): <RETURN> 

Your network number is 192.9.200; is this correct? (y/n): y 

Enter the 6- byte hexadecimal ethernet address for each of the clients 
The correct form is xx:xx:xx:xx:xx:xx 

Client blaise: 8:0:20:0:14:76 

Client albert: 8:0:20:0:8:55 

Client isaac: 8:0:20:0:6:23 

Client Johannes: 8:0:20:0:11:22 

Client immanuel: 8:0:20:0:13:49 

Client tycho: 8:0:20:0:7:33 

The clients and their addresses are: 

1) blaise: 8:0:20:0:14:76 

2) albert: 8:0:20:0:8:55 

3) isaac: 8:0:20:0:6:23 

4) Johannes: 8:0:20:0:11:22 

5) immanuel: 8:0:20:0:13:49 

6) tycho: 8:0:20:0:7:33 

Are the ethernet addresses correct? (y/n): y 

Do you want host numbers automatically assigned? (y/n): y 

Server Information 

Enter the name of the server: archimedes 

The server's hostname is: 

archimedes 
Is this correct? (y/n): y 

Note that you use your network number, your clients' hardware Ethernet addresses (established 
at the outset of the installation procedure), and host numbers for clients and server here. You 
can choose your own host numbers, or have setup assign them automatically. For a discussion 
of network and host numbers, and Ethernet addresses, see the earlier section. Determining Net- 
work Information. 
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The last phase of setup configuration requests information about your tape subsystem: 
Tape Information 

1) 1/4" SCSI tape (st) 

2) 1/2" magnetic tape (mt) 

3) 1/4" archive tape (ar) 

Enter the number for the type of tape: (1-3): 2 

You have specified a 1/2" magnetic tape; is this correct? (y/n): y 

When ti^is last phase has been completed, setup asks you whether you want to institute the 
configuration you have designed and, if you confirm, proceeds to edit several of the database 
files: 

You have completed the configuration questions. 
Continuing will destroy any existing files under /usr 
and any client partitions if you are a server. 

Do you want to beg^n configuration? (y/n): y 

Updating /etc/hosts 

[ . . . A few lines of configuration messages . . • ] 

If your distribution is on two 1/4-inch tape cartridges, setup will prompt you to change to the 
second cartridge about two minutes into its back-end routine. Insert the second tape and type 
'RETURN' to continue the routine; it takes approximately 25 minutes to complete. When 
setup completes its back-end work, your shell prompt returns. You can then continue your 
installation by booting the full UNIX system, as described below. 

4.3.11. Booting the Full UNIX System 

Finally, you boot the full UNIX system. You must first halt the system, using the /etc/ halt com- 
mand. This shuts the system down in an orderly manner, and returns control to the monitor: 

# /etc/halt 

Syncing disks .... done 

> 

and now you can simply boot the UNIX system: 

> b 

Boot: (/t0/;(O,O,O)vmunix 

Load: (/t«A: (0,0,0 )boot 

Boot: (/i«A:(0,0,0)vmunix 

Size: 266240+ 32768-1- 35316 bytes 

Sun UNIX 4.2 (GENERIC) #145: Tue Feb 21 20:35:13 PDT 1984 

Copyright (c) 1984 by Sun Microsystems, Inc. 

[ . . . Many lines of configuration messages . . . ] 

gaia login: root 
# 

You can now use the UNIX system on it).s machine, and now boot any clients that will be served 
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by this machine. Continue now with kernel configuration and, if you have an Ethernet, with 
network configuration. Both of these steps are crucial for system performance reasons. 

4.3.12. Kernel Configuration 

Sun Microsystems' implementation of UNIX provides for a configurable kernel — that is, certain 
system parameters that were hardwired in previous implementations can now be changed. As a 
final step in system installation, all 1-MByte systems must — and all other systems should — 
configure the UNIX system kernel to suit your particular system. This reconfiguration reduces 
the kernel size, thus giving a larger effective memory size to programs. This is especially impor- 
tant if you intend to run the Sun Window System. 

This section begins with a lockstep walkthrough of configuration procedures, which we hope 
provides enough information to take you safely through reconfiguration. If there is anything 
you don't understand or feel comfortable with, please read the sections just following the walk- 
through; they give some explanation of what's going on (describe the layout of the kernel code, 
and the format of the configuration file used by the utility /etc/config to build your system 
configuration). 

For a full discussion of configuring and building system images, see the document Building Sun 
Workstation Kernelt in the TutoriaU section of this manual. 

This configurable system also provides for adding new device drivers to the system, since all the 
kernel object files required to build a new system are present. For procedures, see the Device 
Driver Tutorial in the Sun System Internals Manual. 



4.3.12.1. Making a New Configuration 



This subsection walks you through the procedure for making a new system configuration. If 
your system includes server(s) and client(s), you probably want to go through this procedure 
twice, making one kernel for the server machine (install it in /vmunix), and one kernel for all 
the clients (install it in / pub/ vmunix). 

1. Choose a name for your configuration of the system; here, SYS_NAME. Note that — by con- 
vention — the name should be in all uppercase letters. 

2. Change directory to the /«y»/ con/ directory, and create the configuration file and the direc- 
tory in which the new system will be built. In this example, we assume that you will make 
a copy of the GENERIC file provided with this release, and edit the copy to create your new 
configuration file. Another (perhaps easier) method is to copy one of the stripped-down files 
in /sys/conf and edit it, XYIOO, for example, makes a good starting point for a Model 
lOOU with one Xylogics disk; XYARIOO is a standard file for a Model lOOU with a Xylogics 
disk and a 1/4" tape. XYMT150 is a Model 150U server with 2 Xylogics disks and a 1/2" 
tape. 

# cd /sys/conf 

# cp GENERIC SYS_NAME 

# chmod -f-w SYS_NAME 

# mkdir ../SYS_NAME 

3. Edit SYS_NAME to reflect your system. This is the part of the procedure which takes some 
thought. On the next page, we provide a copy of the GENERIC file. You will notice that the 
file has two different 'types' of lines: lines which describe general aspects of the system 
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(which are, generally, parameters global to all kernel images specified in the configuration 
file), and lines which specify devices 'attached' to the system. We have indicated both 
classes of lines as follows: 

• General system description lines are tagged "**mandatory**". These lines must be 
included in your system configuration file, either exactly as they stand or, if commentary 
indicates variables, with the variables adjusted to fit your system. 

• Device description lines are given and explained. Often, we also refer you to the manual 
entry which covers the device in question. When you edit the GENERIC file, you should 
include only the lines which describe your system's devices. Remember that if you are 
creating a kernel for several clients, the configuration file must include the entire set of 
devices used by all the machines. 
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# GENERIC SUN 

# 

machine sun 

''SUN2" 



cpu 
ident 



timezone 
maxusers 

options 
options 



GENERIC 



8 dst 
4 

INET 
SYSACCT 



#**Mandatory**# 

#**Mandatory**# 

#**Mandatory** If you use "GENERIC as your system identifier, you may use 
the "swap generic" clause in the "config" line below. If you customize the identifier 
to SYS_NAMEy you must either include an "options GENERIC" line or specify at least 
the device where your root file system lives in place of "swap generic". For example, 
the "config" line for a standard Sun lOOU might read: "config vmunix root on xy". 
Finally, if SYS_NAME contains both alpha and numeric characters (as in XYlOO, 
for example), you must enclose the name in double quotes or you will get a syntax 
error when you run / etc/ config ("XYlOO"). 

^♦♦Mandatory** Number and "dst" are variable^ 

^♦♦Mandatory** Number may vary. For most systems, "2" is the proper value for 
maxusers. See the section General System DeBcription Lines, below, for information.^ 

^♦♦Mandatory** INET means include Internet code# 

#Optional,- include only with pseudo-device sysacct. 
Controls inclusion of code to do process accounting — see aeet(2) and aect{b).^ 



config 

pseudo-device 
pseudo-device 
pseu do- device 
pseu do- device 
pseudo-device 
pseudo-device 

pseudo-device 
pseu do- device 
pseu do- device 
pseudo-device 
pseudo-device 

pseu do- device 

controller 

controller 

controller 

disk 

disk 

disk 

disk 

controller 

controller 

disk 

disk 

disk 



vmunix swap generic 



#**Mandatory»* Specify root and swap devices^ 



pty 

bk 

sysacct 

inet 

ether 

loop 

nd 

win 128 
dtop4 
ms3 
kb3 

ingres 

mbO at nexus ? 

ipcO at mbO csr 0x40 priority 2 

ipcl at mbO csr 0x44 priority 2 

ipO at ipcO drive 

ipl at ipcO drive 1 

ip2 at ipcl drive 

ip3 at ipcl drive 1 

xycO at mbO csr 0xee40 priority 2 

xycl at mbO csr 0xee48 priority 2 

xyO at xycO drive 

xyl at xycO drive 1 

xy2 at xycl drive 



#Pseudo-tty's. Needed for network or window system. # 

#Berknet line discipline for high speed tty input - see 6^(4).^ 

#Include only with SYSACCT options clause, above. # 

#*»Mandatory** Internet code - see tnef (4).# 

fjtARP code. Must include if using Ethernet — see arp(4).# 

#**Mandatory** Software loop back network device driver; 
must include if INET — see /o(4).# 

#Network disk. Needed if server or diskless - see n(/(4).# 
^Window system. Number indicates max windows. Must include dtop, below^ 
#Max Screens ('desktops'); required for window system. # 
jl^Max Mice; required for window system - see m«(4).# 
^Max Sun keyboards; required if using any Sun keyboard; 
omit if using serial terminal for console.^ 

^Ingres lock deviceff^ 
lJt**Mandatory«* Multibus code.^ 



#lst Interphase controller - see tp(4).# 

l{^2nd Interphaise controller.^ 

#lst disk on 1st Interphase controller# 

#2nd disk on 1st Interphase controller^ 

^Ist disk on 2nd Interphase controller^ 

^2nd disk on 2nd Interphase controller^ 

#lst Xylogics controller - see xy{4).^ 

#2nd Xylogics controller# 

#lst disk on 1st Xylogics controller^ 

#2nd disk on 1st Xylogics controller^ 

^Ist disk on 2nd Xylogics controller^ 
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disk 

controller 

disk 

disk 

tape 

device 

device 

device 

device 

device 

device 

device 

device 

device 

device 

device 

device 

controller 

controller 

tape 

tape 

device 

device 

device 

device 

device 

device 

device 

device 

device 



xy3 at xycl drive 1 

scO at mbO csr 0x80000 priority 2 

sdO at scO drive flags 

sdl at scO drive 1 flags 

stO at scO drive 32 flags 1 

ropcO at mbO csr OxeeOSOO priority 1 



#2nd disk on 2nd Xylosics controUer^j^ 

#lst SCSI controller# 

#lst disk on 1st SCSI controller^ 

#2nd disk on 1st SCSI controller# 

#SCSI tape# 

#**Mandatory** Raster Op chip - see rope(4).# 

#Sky Floating Point board.# 



skyO at mbO csr 0x2000 priority 2 

zsO at mbO csr OxeecSOO flags 3 priority 2 #CPU ports - see 2«(4).# 

zsl at mbO csr OxeecOOO flags 3 priority 2 #Sun-2 Video Board ports; 

required if using Sun-2 keyboard and mouse.^ 

zs2 at mbO csr 0x80800 flags 3 priority 2 #lst SCSI Board ports.# 

zs3 at mbO csr 0x81000 flags 3 priority 2 #lst SCSI Board ports.# 

octO at mbO csr 0x520 flags Oxff priority 4 #Central Data Octal Card - see 0£t(4).# 

mtiO at mbO csr 0x620 flags Oxff priority 4^Systech terminal MUX — see mtt(4).# 

ieO at mbO csr 0x88000 priority 3 #lst Sun-2 Ethernet Controller^ 

ieO at mbO csr 0x8C000 flags 2 priority 3 #2nd Sun-2 Ethernet Controller^ 



ecO at mbO csr OxeOOOO priority 3 
eel at mbO csr 0xe2000 priority 3 
tmO at mbO csr OxaO priority 3 
tml at mbO csr 0xa2 priority 3 
mtO at tmO drive flags 1 
mtl at tml drive flags 1 
arO at mbO csr 0x200 priority 3 
arl at mbO csr 0x208 priority 3 
cgoneO at mbO csr 0xe8000 priority 3 
bwtvroO at mbO csr 0x700000 priority 3 
bwoneO at mbO csr OxcOOOO priority 3 
vpO at mbO csr 0x400 priority 2 
vpcO at mbO csr 0x480 priority 2 
vpcO at mbO csr 0x500 priority 2 
piO at mbO csr 0xee2000 priority 1 



#lst 3COM Ethernet Controller - see ec(4)# 

#2nd 3COM Ethernet Controller# 

#lst TAPEMASTER tape controller - see tm(4).# 

#2nd TAPEMASTER tape controller# 

#lst 1/2" tape drive on 1st controller. # 

#lst 1/2" tape drive on 2nd controller. # 

#lst 1/4" tape drive - see «r(4).# 

#2nd 1/4" tape drive.# 

>|)tlst Sun Color Board - see cg{4).^ 

iftlst monochrome Sun-2 monitor.^ 

#lst monochrome Sun-1 monitor.^ 

#Ikon Versatec Board - see tfp(4).# 

#lst Systech Centronics/Versatee Board - see «p«(4s).# 

#2nd Systech Centronics/Versatee Board. # 

#Parallel input. Only used on Sun Models lOOU 
and 150U, for keyboard and mouse. 
Not needed if using terminal for console.^ 
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The following configuration XYIOO is a stripped down version of the GENERIC system for 
a system with only a single local peripheral: a Xylogics controller supporting one disk drive. 
It's a good example of a standard configuration file: 

* . . . 

# Model 100 with one Xylogics Disk 

# 

machine sun 

cpu ''SUN2" 

idcnt "XYIOO" 

timezone 8 dst 

max users 2 

options INET 



config 



vmunix root on xy 



pseudo-device pty 

pseudo-device inet 

pseudo-device ether 

pseudo-device loop 

pseudo-device Win32 

pseudo-device dtopl 

pseudo-device msl 

pseudo-device kbl 

controller mbO at nexus ? 

controller xycO at mbO csr 0xee40 priority 2 

disk xyO at xycO drive 

device ropcO at mbO csr OxeeOSOO priority 1 

device zsO at mbO csr OxeecSOO flags 3 priority 2 5^ cpu ports 

device ecO at mbO csr OxeOOOO priority 3 

device bwoneO at mbO csr OxcOOOO priority 3 

device piO at mbO csr Oxee2000 priority 1 

For more examples of standard configuration files, see Appendix C in the paper Building Sun 
Workstation KerneU in the Tutorials section of this manual. 

4. When you have finished editing SYS_NAME, run config^: 

# /etc/config SYS^NAMk 

5. Now change directory to the new configuration directory, ,,/SYS_NAME, and make the new 
system: 



^ Note that if the "ident" field (system name) in your configuration file contains any digits, 
/ete/config prints: "config: Line 5: syntax error" at this point. You may ignore the error message. 



Revision H of 12 March 1984 



4-35 



Installing UNIX for the First Time Sun 100/150 Installation Manual 



# cd .,/SYS_NAME 

# make depend 

[ lots of output . . . ignore the error message^ ] 

^ make 

[ lots of output ] 

The make depend command creates the dependency tree for all system source files. 

6. Now you can install the new system and try it out. 

# mv /vmunix /vmunix.org 

# cp vmunix /vmunix 

# /etc/halt 

The system goes through the halt sequence, then 
the monitor displays its prompt, at which point you 
can boot the system in single-user state 

> b vmunix -s 

The system boots up in single user state, and 
then you can try things out 

# 

7. If the system appears to work, all is well. If the new kernel doesn^t seem to be functioning 
properly, boot /vmunix.org, move it back to (vmunix, and go about fixing your new kernel: 

# /etc/halt 

> b vmunix.org -s 

# mv /vmunix /vmunix.oop8 

# mv /vmunix.org /vmunix 

# ^D [ Brings the system up multi-user ] 
# 

You can now continue with the next phase of installation — loading the manuals, demos, and 
games directories — or, if you do not wish to include this material in your system, with the Net- 
work Configuration section in the System Set-up and Operation chapter. The subsections 
immediately below give background information for configuring the kernel. 

4.3.12.3* Configuration Directory Layout 

The system as shipped contains the essential source and object files in the fsys directory. The 
jsys directory contains several subdirectories that in turn contain the object code modules 
required to build difi^erent parts of the system. The subdirectories in /sys are: 

OBJ Contains the kernel object code plus the header files describing the number of 

devices of each type. 

conf Contains the files describing the configuration of the system and what files are 

required to build the new system. Also contains a README file describing how 
to make a new kernel. Finally, contains the GENERIC system configuration file 



' The 'make depend' may generate a spurioub error message like *../sun/locore.s: no such file or 
directory' at this point, which yo(| may safely ignore. 
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supplied with the distribution. This file may be copied and edited to produce 
your specific system configuration file; procedures are given above. 

h Header files containing definitions and data structures. 

machine Machine-dependent routines for the Sun system — this is a symbolic link to the 

sun directory. 

net Networking files. 

netimp Arpanet IMP support code. 

netinet Internet protocols. 

netpup 3 Mbit Xerox PUP protocol support. 

sun Sun-specific mainline code. 

sundev Sun-specific device drivers. 

sunif Sun network interface code. 

sys General system routines. 

4.3.12.3. Building a Configuration 

Building a new system is a semi-automatic process; most of the fine detail is handled by a 
configuration build utility called /ete/config. /etc/config uses three files as input: 

Specific Configuration File 

This file contains a description of the characteristics of a specific system, plus 
descriptions of the devices that that system can support. Every new version of 
the system has another file of this type. 

files Contains a list of the files required to build the basic kernel. 

fiies.sun Contains a description of the files required to build the specific Sun system. You 

add the names of new driver modules in here when adding drivers to the kernel. 

/etc/config should be run from the conf subdirectory of the system source or object files. 
/etc/config assumes that there is already a directory ../ System JName created, and it places all 
its output files in there. The output of /etc/config consists of a number of files: 

ioconf.c Contains a description of I/O devices attached to the system. 

makefile For building the system. 

Header Files A set of header files whicn contain the number of various devices that will be 
compiled into the systeui. 

After running /etc/config, you must then change directory to the directory in which the new 
makefile was created, and use make to create the dependency tree for the new system. 
/etc/con/^ remind?, you of this when it completes: 

# cd * •/ Sy»tem_Name 
^ make depend 

# 

If you get any other error messages from /etc/config, fix the problems in your configuration file 
and try again. If you try to compile a system that had configuration errors, you will meet with 
failure. 
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4.3.12.4. Format of the Configuration File 

There are two main classes of information in the configuration file: 

• Lines which describe general things about your system. 

• Lines which describe the devices on the system, and what those devices are connected to. 
The two subsections below contain descriptions of the two classes of information. 

In these descriptions, a number can be a decimal integer, a whole octal number or a whole hexa- 
decimal number. Hexadecimal and octal are specified to fetc/config in the same way they are 
specified to the C compiler, namely, a number starting with *0x* is a hexadecimal number and a 
number starting with just a '0' is an octal number. When specifying the timezone, you may 
also use a floating point number. 

Comments are specified in a configuration file with the character *#'. All characters from a '#' 
to the end of a line are ignored. 
Lines beginning with tabs are considered continuations of the previous line. 

4.3.12.4.1. General System Description Lines 

The first seven general description lines in the configuration file are mandatory. They are: 

machine type 

This system is to run on the machine type specified. Only one machine type can appear in 
the configuration file. The legal type for a Sun system is tun. 

cpu type 

This system is to run on the cpu type specified. For a Sun system, legal type is ''SUN2'' 
(enclose in double quotes). 

ident name 

Gives the system identifier — a name for the machine or machines that run this kernel. 
name must be enclosed in double quotes if it contains both letters and numbers. Also, note 
that if name is GENERIC, you can specify the unique config_clause swap generic in the 
config line described below. If you use any other string for name, and you also include an 
options GENERIC line, you can still use the swap generic line. However, if you use any 
other string for name and omit the options GENERIC line, you must specify your root 
and, optionally, swap devices in the config_clautes field. 

timezone numher [ dffi ] 

Specifies the timezone you are in. This is measured in the number of hours west of GMT 
you are. 5 is EST, 8 is PST. Negative numbers indicate hours cast of GMT. If you specify 
dst, the system will convert to and from daylight savings time when appropriate. 

maxusers number 

The maximum expected number of simultaneously active users on this system is number. 
This number is used to size several system data structures. In particular, it controls the 
size of the process table which sets the upper bound on the 'legal* number of user processes. 
Since this table is statically allocated, it cuts into your buffer space; it is thus important to 
set number no higher than necessary for your system. If you are configuring a kernel for a 
single-user Sun Workstation, for a single-user networking node, or — especially — a 1 
MByte system, set number to "2*'. Use "4" only if you anticipate running an unusually 
high number of user processes per machine — for example, if you plan to run 7+ windows 
at a time. 
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options optlist 

Compile the listed options into the system. Options in this list are separated by commas. 
There is a list of options that you may specify in the generic makefile. A line of the form 
♦options FUNNY,HAHA' yields -DFUNNY -DHAHA to the C compiler. An option may be 
given a value, by following its name with '=' then the value enclosed in (double) quotes. 
None of the standard options use such a value. 

config kernelname config__clause9 

Specifies a bootable system image; multiple bootable images may be specified in a single 
configuration file. Here kernelname is the name of the loaded kernel image (normally, 
vmunix). The config_clauses specify at minimum the root device, and may also specify the 
swap device. If you are using GENERIC as your system identifier (described above), or if 
you customized your identifier and also included an options GENERIC line, then your 
config_clause may legally be swap generic. In any other case, you must specify at least 
your root device. For example, if you are configuring a kernel for a Sun lOOU, and your 
ident line looks like this: 

ident "MYlOO" 

your config line might look like this: 

config vmunix root on xy 



4.3.12.4.2. Device Description Lines 

The second class of line in the configuration file describes what devices your system has and 
what they are connected to (for instance, I have a Xylogics xy450 on the Multibus). The device 
description lines for all supported devices are given in the section 4 pages of the Sun System 
Interface Manual; see the 'synopsis' section of the entry for each device. 

Each device description line has the following format: 

devjtype devjname at con_dev morejinfo 

The meaning of the fields is: 

Devjtype 

is one of controller, tape, disk, device, or pseudo-device. These types have the follow- 
ing meanings: 

controller 

is a Multibus disk controller or a Multibus tape controller. 

disk or tape 

are devices that are connected to a controller. 

device 

is something which plugs into the Multibus, like a cartridge tape interfaure. 

pseu do- device 

is something which should be conditionally loaded, but is not really a device. Current 
examples are the pseudo-tty driver and various network subsystems. For pseudo- 
devices, morejinfo may be specified as an integer, that gives the value of the symbol 
defined in the header file created for that device, and is generally used to indicate the 
number of instances of the pseudo-device to create. If you load a subsystem you may 
find it necessary to enable conditional code using an options specification. 
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devjname 

is the name of the device you are specifying. If it is not a pseudo-device, you must give a 
number afterwards — for instance, xycO for a Xylogics controller or arO for an Archive 
cartridge tape controller. 

con^dev 

is what the thing you are specifying is connected to. For example, disk xyl is connected to 
controller xycO. 

morejinfo 

is a sequence of the following: 

car addr 

Specifies the address of the csr (command and status registers) for a device. Must be 
specified for all Multibus controllers and for all devices connected to the Multibus. 

drive number 

For a disk or tape, specifies which drive this is. 

flags number 

These flags are passed to the device driver at system initialization time. 

priority level 

For devices which interrupt on the Multibus, specifies the interrupt level at which the 
device operates. Use priority 1 if not needed. 

A ? may be substituted for a number in two places and the system will figure out what to fill in 
for the ? when it boots. You can put question marks on a con_dev (for example, at xyc?), or on 
a drive number (for example, drive ?). This allows redundancy as a single system can be built 
which will boot on different hardware configurations. 

4.3.13. Loading the Manuals, Demos, and Games Directories 

The seventh file on the distribution tape(s) contains tar images of the /uar/man directory 
(online manuals), /usr/demo directory (demonstration programs), and /usr/ games directory 
(games). You can load all or part of this file if you want to. For some configurations, disk 
storage space will be a consideration: the online manuals require approximately 2.1 MBytes, 
/usr/demo requires 3.75 MBytes, and /usr/ games takes 1.8 MBytes. 

There is one basic procedure for loading to a standalone system from a quarter-inch tape, and 
one for the nine- track tape. These follow. If your system is a file server rather than a stan- 
dalone system, simply change directory to /pub/ usr rather than /usr initially, then complete the 
identical sequence of commands. 

To load from quarter-inch tape: 

1) Become super-user. 

2) Insert the first quartef-inch tape cartridge. 

3) Type the following sequence of commands (choosing the directories you want, at the last): 

# cd /uBt (or /pub/usr if you are loading on a fi!eserver) 

# mt -f /dev/nrarO rew 

# mt -f /dev/nrarO fsf ft 

# tar xvf /dev/rarO man demo games 
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To loa4 from half-inch tape: 

1) Becpme super-user. 

2) Mount the half-inch tape. 

3) Type the following sequence of commands (choosing the directories you want, at the last): 

5^ cd /usr (or /pub/usr if you are loading on a fileserver) 

# mt rew 

# mt fsf 6 

^ tar XV man demo games 



4.3.14. The Next Step 

Unless you have to install UNIX on systems without tape drives (procedure given in the follow- 
ing chapter), you have now completed the portion of installation in which you need the distribu- 
tion tape. However, there are a few other installation matters — like network configuration and 
setting up the mail system — which you may not want to ignore. We continue with these 
topics in the chapter Syattm Set-up and Operation. Take a glance at it now. 
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Installing UNIX on Systems without Tape Support 



This chapter describes the process for installing the UNIX system onto a workstation which does 
not have a tape drive installed. The process involves installing the UNIX system across the Eth- 
ernet from a system which does have a tape drive. Throughout this chapter we refer to the 
"remote host" and "target" machines. The remote host is the machine with the tape drive; the 
target is the machine without it. 



CAUTION: if you are upgrading your Sun Model 100 or 150 rather than starting with a sys- 
tem 'fresh from the box,' please heed the warning on the front page of this manual. SUN-1 sys- 
tems which are upgrading must not attempt to install this release of the system until all Mul- 
tibus memory has been removed or disabled, and — for an upgrade from a Xylogics 440 to a 
Xylogics 450 — cabling has been re-routed. Disk drive switches may also need resetting. Make 
sure you have followed the hardware upgrade procedures given in Sun's Upgrade Installation 
Guide before proceeding. 

CAUTION: If you are upgrading your system software, rather than beginning for the first 
time, read the Upgrading System Software chapter BEFORE proceeding here. The chapter gives 
procedures for saving and rebuilding your existing root and /usr file systems 



5.1. Overview of the Installation Procedure 

Here are the steps required to install the system over the network: 

1. Complete installation of the UNIX system on a Sun System equipped with a tape drive — 
your "remote host" or "network disk server" — as described in the chapter. Installing UNIX 
for the First Time. 

2. Determine network information necessary for installation: the target's hardware Ethernet 
address and Internet address, and the remote host's host number (in hexadecimal). 

3. If your remote host is configured as a standalone system rather than as a network disk 
server, you must turn its /usr file system into a public network disk. If your remote host is 
already configured as a server, this step is unnecessary. 

4. Load the mini file system onto the public disk from the boot tape. 

5. Boot diag over the network; run diag to format (if necessary) and label your disk. 
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6. Boot the standalone copy program over the network. Run copy to copy a mini-file system 
over the network into the swap area on your disk. 

7. Boot the mini- UNIX system. 

8. Edit the /etc/ hosts and /.rhosts files. 

9. Mount the release tape on the remote host. 

10. Extract the root file system from the tape. 

11. Boot UNIX in single user state. 

12. Run the setup program to extract the /usr file system from the tape and initialize the net- 
work files. 

13. Boot the full UNIX system 

14. Load the manuals, demos, and games directories if you wish. 

Now read the sections which follow. There should be enough detail there to walk through the 
remote installation procedure. In all the examples, what you type is shown in boldfaced 
text like this. Boldfaced text is typed exactly as it appears. Some places we have shown parts 
of command in italic text like this, and this means that there is something that must be substi- 
tuted at that point. Italic characters are variables. 

Two very important variables which you will see in the examples — and have already seen if 
you have installed UNIX on your remote host — are tape and disk. Where tape appears, replace 
it with the correct device abbreviation for your tape drive: 

Table 5-1: Tape Device Abbreviations 



Abbreviation 



Device 



mt Nine-track magnetic tape 

ar Archive quarter-inch tape 



Where disk appears, replace it with the correct device abbreviation for your disk: 

Table 5-2: Disk Device Abbreviations 



Abbreviation 



Device 



xy Xylogics 450 disk controller 

ip Interphase 2180 disk controller 



You can correct typing errors at any time. The DEL key backspaces over and erases characters, 
and the control-U key (hold down the CONTROL key while typing the letter U) erases the 
entire line typed so far. 

If you need to get back to the monitor for any reason, you can abort by typing 'SET-UP A' 
(hold down the SET-UP key while typing 'A') or 'ERASE-EOF A' on the Sun Workstation key- 
board at any time. If you are using a standard terminal as a console, the BREAK key generates 
an abort. 
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5.2. Determining Network Information 

Before beginning the installation procedure, you need to know the hardware Ethernet address of 
the target machine, the target's full Internet address (network number and host number), and 
the host number (in hexadecimal) of the remote host. You will use these addresses later in the 
installation procedure. 

To obtain the hardware Ethernet address of the target, power up the target workstation. You 
should see the PROM monitor's sign on messages, one of which is the Ethernet address. Stop 
the auto boot immediately by aborting — type 'SET-UP A' (hold down the SET-UP key while 
typing *A'), 'ERASE-EOF A', or BREAK — and then you should see the monitor's prompt, 
which is a > sign: 

Self Test completed successfully. 

Sun Workstation, Model Sun-1/lOOU or Sun-l/150U, type of keyboard 
HOM Rev N, somejnumber^MBytet memory installed 
Serial i^aomejnumber, Ethernet address n:n:n:n:n:n 

Auto-boot in progress . . . 

abort by typing 'SET-UP A', 'ERASE-EOF A', or BREAK here 

Abort at «ome address 
> 

Copy down the full hardware Ethernet address. Addresses are given as a six-byte hexadecimal 
value. Each byte of the address is separated by a colon. A typical address might be 
'8:0:20:0:14:76'. 

Internet addresses consist of two parts: a network number, and a host number. For remote 
installation, you need the target's full Internet address, and the remote host's host number (in 
hexadecimal). 

Network Number 

The network number is an arbitrary value used to uniquely identify multiple networks. If 
you have been assigned a network number by ARPA, use that number; if not, you may use 
Sun's default network number: 192.9.200. By this point in the installation procedure, you 
probably know your network number. If in doubt, check the /etc/ hosts file on the remote 
host machine. Entries consist of each machine's full Internet address and name, for exam- 
ple: 

192.9.200.48 augustus 
192.9.200.50 Julius 
192.9.200.52 claudius 

Here, Julius' Internet address is 192.9.200.50; his network number is 192.9.200, and his host 
number (in decimal) is 50. 

Host Number 

The host number is also arbitrary — except that it must be between 1 and 255 — and is 
used to uniquely identify each node on your network. The host number is the final com- 
ponent of the full Internet address; it follows the network number. Since you must assign 
your target a unique number, check the /etc/hosts file on the remote host to make sure 
you're not using an address already in use. 

Finally, find the entry for the remote host in /etc/hosts, and note the machine's host number. 
Since the host number entries in /etc/ hosts are in decimal, and you need the remote host's host 
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number in hexadecimal, you will probably need to convert. You can use adb for this if you wish: 

host% adb 

Otho»t_nttmber_in_decimal = X 
h OS t_number_jn_hez 
D 
host% 



5.3. Setting up the Remote Host 

DO THIS IF THE REMOTE HOST IS NOT A NETWORK DISK SER VER. 

If your remote host is already configured as a server, skip to the next step. 

If the remote host machine is not a network disk server, turn the /uar file system into a public 
network disk by adding two lines to ndJocal to reference /dev/ipOg (for an Interphase disk con- 
troller) or /dev/zyOg (for a Xylogics disk controller). The lines should look like this: 

user /der/ditkOg -1 -1 -1 
son 

Then enable the network disk server: 

# cd /dev 

# MAKEDEV nd 

# /etc/nd - < /etc/nd. local 

Next, make the /uar disk into a public disk so that it can be accessed across the network by 
doing the following sequence of commands: 

# mkdir /usr/stand 

# cp /stand/* /usr/stand 

# In -s /usr /pub 

# cp /boot /pub/boot 

# cd /usr/mdec 

if installboot bootnd / dev/ disk 0^ 

# sync 
# 

Then proceed with the next step. 

5.4.. Loading the Mini File System to the Server 

Now load the mini file system onto the public disk from the boot tape with the following 
sequence of commands. Remember to replace tape with mt for the nine-track tape, or ar for 
the Archive quarter-inch tape. Also, if you are using a nine-track tape, use 20 for bUe_Jactor 
('bs=20b'); use 126 for a 1/4-inch tape ('bs=«126b'): 



5-4 Revision H of 12 March 1984 



Sun 100/150 Installation Manual Installing UNIX on Systems without Tape Support 



# mt — f /dey/nrtapeO rew 

# mt -t /dey/nrtapeO fsf 3 

# dd it=/dey/nrtapeO of=s/pub/minif8 hs=blk_Jactorh 

# »ync 

# 

This takes about three minutes using a 1/2-inch tape, and less using a 1/4-inch cartridge. 

5.5. Running Diag 

Now, you start to work on your target machine, and install UNIX from the remote host. The 
first step is to format the disk with the diag utility. You boot diag from the network server 
with a boot command: 

> b ec{Ofhost_jiumber)Bta.nd/diti,^ 

Remember to replace ho8t_number with the remote host's hexadecimal host number (obtained 
earlier). If you have more than one Ethernet Controller Board in your system, and you are 
booting from the second, third, etc., replace the "0" in the above command with the controller's 
address on the Multibus (in hex). 

The monitor should boot diag from the network disk server. When diag starts up, it displays a 
sign on message: 

Disk Initialization and Diagnosis 

When asked if you are sure, respond with 'y' or 'Y' 

Diag first asks you a series of questions about the disk you will be using. The answers to these 
questions 'configure' diag to work with that specific hardware. The first thing diag wants to 
know is the type of disk controller to use. Diag displays a menu of the different disk controller 
types. 

Diag^s second question concerns the address of the controller on the Multibus. The table below 
shows the default addresses for disk controllers*. 

Table 5-3: Default Addresses for Disk Controllers 



Address (hex) 
Controller Type 

1st Controller 2nd Controller 



Interphase SMD-2180 40 48 

Xylogics 450/440 ce40 ee48 



Next, diag wants to know the unit number of the disk — is usually the correct answer if you 
only have one disk, and the type of disk drive you are working with — diag displays a menu of 



* * Note that if you have one Xylogics SMD Controller and one Interphase Controller in your 
system, you cannot use the default addresses (as the Interphase Controller sees only four bytes). 
The Interphase must be configured to be at address 48, and the Xylogics at ee40. See the Hardware 
Configuration and Expantion chapter for board configuration procedures. 
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the different disks. When you have specified which disk drive you are using, diag then displays 
a table of the physical data about that disk, which includes the number of cylinders, number of 
alternate cylinders, number of heads, and number of sectors per track. 

At this point, diag knows all it needs to know about the disk, and it displays its prompt: 
diag> 

One of the responses to this prompt can be the h (for help) command. If you use the h com- 
mand, diag displays a list of its commands. 

5.5.1. Formatting the Disk 

If you are starting with a completely new disk, you will need to format the disk first. If you are 
not starting with a completely new disk, you can skip to the next topic. Labelling the Disk. 

Before formatting, clear any outstanding errors by typing the clear command: 

diag> clear 

clear 

diag> 

Next, type the format command. Diag then warns you that formatting a disk destroys all 
information which might alrea^ly be stored on that disk, and asks for confirmation before going 
ahead and doing the job: 

diag> format 

format/verify, DESTROYS ALL DISK DATA! 

are you sure? y 

^ of surface analysis passes? 5 

Use five surface analysis passes for a completely new disk; use one pass for a disk which has 
been formatted in the past and is known not to have any bad spots. Formatting a disk takes 
anywhere from a half-hour to four hours depending on how many passes you select, the size of 
the disk, and the type of controller you happen to have. For example, the format phase takes 
about thirty minutes for one surface analysis pass on an 84-MByte disk, using an Interphase 
SMD-2180 disk controller, and a slightly shorter time using a Xylogics 450 or 440 controller. 
Diag displays the current cylinder number as it formats each cylinder. 

5.5.2. Labelling the Disk 

A disk must be labelled after it has been formatted. The purpose of a label is to record (in a 
well known place on the disk) information about how the disk is divided up into partitions for 
different purposes such as swap space and file systems. Diag labels a disk in response to the 
label command. Here is an example of using the label command to write a label on the disk 
which was formatted in the discussion above. When you give the label command to diag, it asks 
if you want to use the logical partition map that is "built in" to the program: 

diag> label 

label this disk... 

OK to use logical partition map 'Fujitsu-M2312K (Sun D84)' ? y 

Are you sure you want to write? y 
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Then, when diag has labelled the disk, it verifies the label it has just written. There is in fact a 
separate verify command, but diag automatically does a verify as part of the labelling process. 

When the 'diag>' prompt returns, get back to the monitor by responding "q" (for 'quit'). 

5.6. Loading the Mini UNIX System 

Now boot the standalone copy program from the disk server. Remember to replace disk with 
xy for the Xylogics controller, or ip for the Interphase disk controller; and replace host^number 
with the remote host's host number (in hex). Also, if you are not booting from the first Ether- 
net Controller Board in your system, use the board's Multibus address (in hexadecimal) rather 
than "0" in the boot command: 

> b ec{0,ho8t_number)Btaknd/ copy 
Boot: ec(0,Ao«<_n«m&cr)stand/copy 
Load: ec(0,Ao«(_n«m6cr,0)boot 

Boot: ec(0,Ao«t_n«m6cr,0)stand/copy 

[ . . . messages displaying sizes of copy program . . . ] 

Standalone Copy 

From: ec(0,Ao«L')tim&er,0)mmif8 

To: disk{Ofi,l) 

The load process takes about four minutes. This process loads the mini file system into the 
swap area on the disk. When it completes, the copy program returns control to the monitor: 

Copy completed 
> 



5.7. Booting the Mini UNIX System 

The next step is to boot UNIX in single user state and ask for its root file system: 

> b ec{Ofhodt_numbcr)hooi 

When UNIX comes up and asks for its root file system, tell it "rfi«AO*". Since this notation 
looks a bit ambiguous, let me clarify: if you are using a Xylogics controller, your root device is 
xyO* ; if you are using an Interphase controller, it is ipO* — the asterisk is part of the device 
name: 

Boot: </t«A;(0,0,l)ymunix -as 

[ . . .lots of messages . . . ] 

root device: diskO* 
# 

At this point, the system may gently remind you to reset the date and time: 

WARNING: clock gained 16845 days - CHECK AND RESET THE DATE! 

You can do this when your prompt returns, with the date{l) command. 
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5.8. Setting the Date 

Set the correct system date and time by using date{l): 

if date yymmddhhmml.sa] 

yy here is the last two digits of the year; mm specifies month; dd designates day of the month; 
hh is hour (on a 24-hour clock); the next mm is minutes elapsed; and the optional .ss specifies 
seconds. The system echoes the date set back to you. 

5.9. Editing the /etc/hosts and /.rhosts Files 

Now you must edit the /etc/ hosts file on both the remote host and target machines, to make 
them aware of each other's existence. Also, edit /.rhosts on the remote host only. Proceed as 
follows: 

1. On the remote host machine, edit the /etc/ hosts file, and add an entry for the target 
machine. There must be an entry for the remote host as well; if it's not there, add it. 
Entries in /etc/hosts consist of each machine's full Internet address (network number and 
host number), and the machine's name. For example, assuming your remote host is called 
'krypton,' and your target is 'gaia,' the entries might look like this: 

192.9.200.1 krypton 

192.9.200.23 gaia 

Here, 192.9.200 is being used for the network number; the remote host's host number is 1, 
and the target's host number is 23. 

By now, you probably know your network number, and have a host number ready to assign 
your target — if you're confused, see the earlier section. Determining Network Information. 

2. Still on the remote host machine, edit the / .rhosts 1a\e, adding an. entry (hostname only) for 
the target machine. This will allow you to perform remote processes 'on' the remote host 
'from' the target machine at the super-user level (for example, the remote extract in the 
next phase of installation). If the file does not exist, create it. 

3. Now move to the target machine, and edit /etc/ hosts (which should be nearly empty). Add 
the same two lines discussed ih step 1: one entry for the remote host and one for the target 
machine. 

4. Run ifconfig on the target machine: 

# /etc/ifconfig ecO yow^targetjname 

5.10. Loading the Root File System 

Now you must mount the distribution tape on the remote host's tape drive. Then run the rxtr 
(remote extract) shell script on the target machine to copy the root file system across the Ether- 
net. Again, use xy for the Xylogics disk controller, or ip for the Interphase disk controller to 
replace disk, and mt for the nine-track tape, or ar for the Archive quarter-inch tape to replace 
tape: 
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^ d\Be=disk tape=f ape host^ server _name rxtr 

[ . . .incredible amounts of messages . . . ] 

Root filesystem extracted 
# 

The extraction process takes ten to twenty minutes. The next job is to configure your system 
and load the /usr file system. 

6.11. Booting the UNIX System in Single-User State 

Now type a couple of sync commands to flush all I/O activity to the disks, then get back to the 
monitor by typing 'SET-UP-A' or 'ERASE-EOF-A'. The monitor responds by displaying a 
message like: 

Abort at some address 

When you see the monitor > sign, boot the UNK system in single-user state: 

> b vmunix — s 

[ . . .incredible amounts of messages . . . ] 
# 

5.12. Using Setup to Configure Your System 

At this point you invoke the setup program to configure your system. 

Setup is essentially a system configurator in two parts: it consists of an interactive front-end 
which gathers the information necessary to configure your system by conducting a dialogue with 
you, and a non-interactive back-end which uses this information to do the actual configuration. 
During the dialogue, setup does consistency and error checking to ensure that the configuration 
will work. If errors are detected, they are reported to you, and you are asked to enter corrected 
information. 

For standalone systems booting from a remote tape drive, the setup dialogue runs as follows. In 
the example, what you might type in is shown in boldface type like thb; whatever is simply 
displayed on the workstation monitor is shown in Roman type like this. Italic items are vari- 
ables which you must substitute. 
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We invoke the setup program by typing the setup command. Setup begins by requesting global 
information: 

^ setup 

Sun Microsystems Configuration System 

Global Information 

1) network disk server 

2) standalone 

3) standalone with remote tape 

Enter the number for your environment: 3 

You have a standalone system with remote tape; is this correct? (y/n): y 

Note that the program asks you to verify configuration information after each 'phase' of 
configuration is complete, it is extremely difficult to undo system configuration, so be careful 
with your responses: 'y' casts things in concrete, and 'n' allows you to start the phase over 
again. You can also type 'q' to any prompt to quit the setup program and return to the shell — 
this allows you to annihilate what you have done and start over, if you have to. 

Next, setup establishes your workstation's identity: name and address: 

Host Information 

Enter your hostname: your^hostname 

Network numbers may be either class A, B or C 
Their formats are: 

Class A: nnn ( <= nnn <= 127) 

Class B: nnn.bl (128 <= nnn <= 191) 
Class C: nnn.bl. b2 (192 <= nnn <=» 255) 

bl and b2 are one byte (0-255) quantites 

Enter your network number (default is 192.9.200): <RETURN> 

Your network number is 192.9.200; is this correct? (y/n): y 

Enter your host number 

This is a number between 1 and 255: your_host_numher 

Your hostname and host number are: 

yourjkostnamei your_host_number 
Is this correct? (y/n): y 

Note that you use your network and host numbers here. See the section above. Determining 
Network Information, if you need explanation of these. 

The last phase of setup configuration requests information about your remote host's tape sub- 
system: 
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Tape Information 

1)1/4" SCSI tape (st) 

2) 1/2" Magnetic tape (mt) 

3) 1/4" Archive tape (ar) 

Enter the number for the type of tape: (1-3): 3 

You have specified a 1/4" Archive tape; is this correct? (y/n): y 

Enter the name of the remote host that the 
1/4" Archive tape is attached to: server_name 

Enter the host number for aervcrjname; s'8_host_number 

The 1/4" Archive tape is attstched to aervcr_jiame with host number s 's_hoat_number 

Is this correct? (y/n): y 

When this last phase has been completed, setup asks you whether you want to institute the 
configuration you have designed and, if you confirm, proceeds to edit several of the database 
files: 

You have completed the configuration questions. 
Continuing will destroy any existing files under /usr 
and any client partitions if you are a server. 

Do you want to begin configuration? (y/n): y 

Updating /etc/hosts 

[ . . . A few lines of configuration messages . . . ] 

If your distribution is on two 1/4-inch tape cartridges, setup will prompt you to change to the 
second cartridge very shortly after it begins its back-end routine. Insert the second cartridge 
and type 'RETURN' to continue the routine; it takes approximately 25 minutes to complete. 
When setup is done with its back-end work, your shell prompt returns. You can then continue 
your installation by booting the full UNIX system, as described below. 

5.13. Booting the Full UNIX System 

Finally, you boot the full UNIX system. You must first halt the system, using the /etc/ halt com- 
mand. This shuts down the system in an orderly manner, and returns control to the monitor: 

# /etc/halt 

Syncing disks .... done 

> 

and now you can simply boot the UNIX system: 
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>b 

Boot: (/t«A;(0,0,0)ymunix 

Load: (/t«i(; (0,0,0 )boot 

Boot: (/t«A:(0,0,0)vmunix 

Size: 266240+ 32768+ 35316 bytes 

Sun UNIX 4.2 (GENERIC) #145: Tue Feb 21 20:35:13 PDT 1984 

Copyright (c) 1984 by Sun Microsystems, Inc. 

[ . . . Several lines of configuration messages . . . ] 

gaia login: root 
# 

You can now use the UNIX system on this machine. 

5.14. Loading the Manuals, Demos, and Games Directories 

The seventh file on the distribution tape(s) contains tar images of the /usr/man directory 
(online manual pages), /usr/demo directory (demonstration programs), and /usr/ games direc- 
tory (games). If these have been loaded on your remote host, you can load all or part of these 
files if you want to. Space may be a consideration: /usr/man consumes 2.1 MBytes, /usr/demo 
consumes 3.75 MBytes, and /usr/ games takes 1.8 MBytes. 

1) Become super-user. 

2) Mount the 1/2" distribution tape or insert the first 1/4" cartridge. 

3) Type the following on your target machine: 

# cd /u»r 

# rsh serverjname mt — f /dey/nrtapeO rew 

# rsh serverjname mt -f /dey/nrtapeO tat 6 

Then type the following command, specifying only the directories you want (man and/or 
demo and/or games). If you are using a 1/2" tape, use 20 for blk_factor; use 126 if you 
are using a 1/4" tape: 

# rsh serverjname dd it^/dev/nrtapeO hB=iblk^actorh \ tar xfpB - man demo gam* 
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Chapter 6 
System Set-Up and Operation 



This chapter describes procedures used to set-up and operate a Sun Workstation UNIX system. 
Set-up material applies to a first-time installation: in most cases, it includes background infor- 
mation on and installation procedures for the various available utilities — like the mail system, 
9yslog, uucp, and USENET — you may wish to use. Operations procedures described here are 
used periodically to reboot the system, analyze error messages from devices, do disk backups, 
monitor system performance, and so on. 

6.1. Network Configuration 



0.1.1. Setting up a Gateway Machine 

If you have a machine with two Ethernet Boards, you must edit /etc/ hosts and /etc/rc. local 'by 
hand' to set up a proper configuration. Note that since each machine on a network must have a 
unique hostname associated with each unique Internet address, a machine with two boards must 
have a 'second identity'; it must be assigned a second hostname ^rnd Internet address. Proceed 
as follows: 

1. Edit /etc/ hosts on the gateway machine, and add a line for the machine's 'second' hostname 
and address. For example, say "jekyll" has two Ethernet Boards: the machine is a server for 
a network of clients, and also is a gateway to another network containing a printer and so 
on. Several lines of /etc/hosts might look like this: 

# Fantasy Local Net 192.9.200 ~ lOMb/s Ethernet ~ Engineering 

# 

192.9.200.1 jekyll loghost datehost 

192.9.200.2 usher 

192.9.200.3 lenore 
[ etc. ] 

# Fantasy Local Net 192.9.4 - lOMb/s Ethernet - Marketeering 

# 

192.9.4.1 quasimoto 

192.9.4.2 godzilla 

192.9.4.3 rodan 
[ etc. ] 

Add an entry for the machine's second address: 
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# Fantasy Local Net 192.9.200 - lOMb/s Ethernet - Engineering 

# 

192.9.200.1 jekyll loghost datehost 

192.9.200.2 usher 

192.9.200.3 lenore 
[ etc. ] 

# Fantasy Local Net 192.9.4 - lOMb/s Ethernet -- Marketeering 

# 

192.9.4.1 quasimoto 

192.9.4.2 godzilla 

192.9.4.3 rodan 

192.9.4.4 jekyll-hyde 
[ etc. ] 

For administrative puposes, it makes sense to use two similar hostnames — people on both 
nets can address the machine by the same name, and you can tell the difference. 

2. Edit /etc/ re. local, and add an 'ifconfig' line mapping the machine^s second hostname and 
Ethernet Board. Taking our example above, here is the relevant line from the file before: 

/etc/ifconfig ecO jekyll -trailers up 

and after: 

/etc/ifconfig ecO jekyll -trailers up 
/etc/ifconfig ecO jekyll-hyde -trailers up 

3. Finally, if you wish, you can copy the gateway's /etc/ hosts file to all machines on both net- 
works. This is not necessary, but may make for ease of administration. 

6.1.2. Reducing Network Overhead 

It is possible to have most of the advantages of living in a network environment without run- 
ning the network daemons — rwhod{SC) and routed{SC) — on every machine. For systems 
with only 1 MByte of local memory, it may be desireable to disable the daemons, or run them 
only on specific machines, so that the space consumed by them can be made available for other 
purposes. When running, routed and rwhod are actively doing something many times a minute, 
and so leave many of their pages in memory almost all the time. For a 1-MByte system with 
600K of available user memory, the memory thus effectively consumed is about 1%. Combined, 
both daemons use up about 14% of available user memory. 

rwhod allows the programs rwho(\C) and ruptime(\C) to return status information about 
machine usage of hosts on the local network. Unless you really need this information, we sug- 
gest you do not run rwhod. By default, rwhod is not run. If you choose to run it, remove the 
comment mark (a '^' in column 1) from the following line in /etc/ re: 

#/usr/etc/in.rwhod & echo -n ' rwhod' >/dev/console 

Normally, routed, the routing daemon, runs on each Sun Workstation, and maintains network 
routing information that enables your machine to pick the best path for sending packets to 
external networks, routed consumes a small amount of memory and CPU time running an algo- 
rithm to keep accurate information about the topology of the local network. 

Whether or where you should run routed depends on your system configuration. In general, if 
you have more than 1 MByte of memory in your workstation then it probably isn't worth 
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thinking about whether you should run routed, just run it. If your memory is limited, see which 
one of the following best applies to you, and follow through: 

1. If you have no gateway machines in your local network then you don't need to run routed. 
You can disable the daemon by removing (or commenting out — insert a '^^' before each 
line) the following three lines in your /etc/rc.hcal file: 

if [ -f /usr/etc/in.routed ]; then 

/usr/etc/in.routed & echo -n ' routed' >/dev/console 

fi 

2. If you are a gateway or a server for diskless nodes then you must run routed. 

3. If you have only 1 MByte of memory and only one gateway in your local network, then you 
can run routed only on the gateway machine, and disable it on all other nodes. All 
machines on the local network can then redirect packets going to another accessible network 
through this gateway machine. To do this, edit the /etc/rc.local file on all machines except 
the gateway {gateway, in the example). Find the line that says: 

echo -n 'local daemons:' > /dev/console 

Insert the following two lines just before it; 



/usr/etc/route add gateway 1 

echo ' /usr/etc/route add gateway V 



> /dev/console 



Then, find the following three lines and comment them out (insert a '^' before each line) or 
remove them: 

if [ -f /usr/etc/in.routed ]; then 

/usr/etc/in.routed & echo -n ' routed' > /dev/console 

fi 

4. Finally, if you have only 1 MByte of memory and you have more than one gateway in your 
local network and you are running diskless, you can use your server's routing tables. Edit 
/etc/rc.local file on all clients of the server machine {server, in the example), and add the 
jfollowing lines: 

/usr/etc/route add server 1 

echo ' /usr/etc/route add server V > /dev/console 

Then comment out or remove the daemon's lines: 

if [ -f /usr/etc/in.routed ]; then 

/usr/etc/in.routed & echo -n ' routed' > /dev/console 

fi 

Since a diskless node cannot run when its server is down, this always works; however, it 
causes packets to be sent through the server, loading it down. 

In all other cases you should run routed. 

6.1.3. Network Security — / etc/ hosts. equiv and .r hosts 

Network security is implemented at two levels: first, at the machine or node level, and, second, 
at the individual user level. The /etc/ hosts. equiv and .rhosts files, respectively, control access at 
these levels. The security-checking process goes like this: 
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1. When a user initiates a remote process on another machine {rlogin, rah or rep, for exam* 
pie), the system first checks for an entry for this user in /etc/paaswd on the remote 
machine. If no entry is found, the user will be denied access: if he is trying to rlogin to the 
machine, he will be prompted for a password and then get a "Login incorrect" message; if 
he is attempting a rep or rsh, he will get a "Login incorrect" message. 

2. If an entry for the user is found in /ete/passwd, the system next checks for his machine's 
hostname in the other machine's fete/ hosts. equiv file. If the hostname is found, the user 
gains access. 

3. If no /ete/ hosts. equiv entry is found, the system checks for a line with his hostname (and, 
optionally, username) in the .r hosts file in his home directory on the other machine. If the 
entry is found, the user gains access. 

If no entry is found in either /etc/ hosts. cquiv or ~ USERNAME/ .rhosts, but the user is in 
/ etc/ passwd, the user is allowed to rlogin to the msichine after giving his password, but gets 
"Permission denied" messages when attempting remote processes like rep or rsh. 

The single exception to this security scenario is the super-user: the system skips the second- 
level check (/etc/ hosts. equiv is not checked), and goes directly to looking at /.rhosts. 

So, if you want to allow access to your machine by all users on another specific machine, include 
an entry for each user in /ete/passwd and include the machine's hostname in your 
/etc/ hosts. equiv file. For example, if my machine's hostname is gaia, and I want to allow any- 
one on host kepler to gain access to gaia, I simply edit my /etc/ hosts. equiv file as follows. The 
file is just a list of hostnames, one per line: 

core 

ganymede 

krypton 

Add kepler's name to the list: 

core 

ganymede 
krypton 
kepler 

Now all users who can gain access to kepler can also freely rlogin{l) to gaia (without being 
asked for a password), and can rep(l) from and use rih(l) on gaia, provided they are in gaia's 
/ etc/ passwd G\e. 

If you want to allow access to some users on a particular machine but not all, do not put the 
machine's hostname in /etc/ hosts. equiv. Instead, put it in the .rhosts file in each user's home 
directory on your machine (~ USERNAME/ .rhosts). Note that, to avoid some security prob- 
lems, this file must be owned by either this user or root, and must not be a symbolic link. The 
.rhosts file has a slightly different format than /etc/ hosts. equiv: /etc/ hosts. equiv accepts only 
hostnames; .rhosts accepts a hostname and, optionally, a user name on each line. Format is 
best illustrated by an example. I can allow user donald at host canard to have access to my 
machine, gaia, and keep other users of canard out by (1) removing other users' entries from 
/ etc/ passwd {or changing their passwords), (2) making sure canard is not in my /etc/ hosts. equiv 
file, and (3) adding an entry for donald at canard to / usr/ donald/ .rhosts. The entry looks like 
this: 

canard donald 

Note also, that this means donald only has access when he's coming from canard; if he tries to 
use gaia from another host, he must know his password to be able to rlogin and can't complete 
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remote processes. Of course, if he can rlogin he can always doctor his .rhosta file (if you have 
given him a home directory). This brings up two points: 

1. The only way to achieve anything resembling security in a hostile environment is to exclude 
users from the /etc/passwd file; once someone knows a password, he's in. If this concerns 
you, you should also be especially careful to protect /.rhosts properly — make sure it is 
writable only by root. Clearly, tight security has not really been an issue in the administra- 
tion of previous UNIX systems; the goal has been to facilitate, rather than deny, access. 

2. If you are dealing with a more open environment, the easiest way to administer machine 
access at the user level is to give each 'trusted* user an account (in /etc/pasawd) and a home 
directory on your machine(s), and ask each user to create his/her own .rhosts file in his/her 
home directory on the machine(s). 

6.1.4. Making 1.1 Networks Compatible with Existing Networks 

The shift in network addressing format in Release 1.1 should only be a concern for you if 

• You have a network of machines running version 1.0 (or lower) of Sun software, and you 
want them to communicate with your new workstation(s) running 1.1, or 

• You have a machine which cannot perform ARP (an older VAX, for example), and you want 
it to talk to your 1.1 Sun's. 

If neither of these is the case, don't worry about it. 

To make machines running 1.1 talk to 1.0 networks or machines which do not respond to or 
perform ARP, you can do one of three things: 

1. The best path is to convert your 1.0 network to the Class C addressing scheme described in 
the previous section. If this is impossible in your system — for example, if you have older 
Vaxen that cannot perform ARP (some 4.1c machines) — then try solution 3. Otherwise, 
we urge you to convert. 

This is easier than it sounds. You'll need to assign your old network a new network number 
(use "192.200.1" if you wish); assign each machine on the old network a new, unique host 
number between 1 and 254; and, finally, edit the /etc/ hosts file and change your old network 
number to your new network number, and identify each host with its host number. For 
example, if my old /etc/ho^ts file looked like this: 



125.5143 


alph^ 


125.5204 


beta 


125.6422 


gamma 


125.0x5245 


delta 


125.0x2226 


epsilon 


7 one might look like tl 


192.9.200.1 


alpha 


192.9.200.2 


beta 


192.9.200.3 


gamma 


192.9.200.4 


delta 


192.9.200.5 


epsilon 



In the example above, "192.9.200" is the network number, and "1" is alpha's host number. 

Then, install /etc/ hosts on all systems. Finally, reboot any machine whose host number you 
have changed. 
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2. A second solution is to retain your Class A addressing scheme from 1.0, but make sure all 
host numbers are smaller than 1024, so that ARP can be performed. 

As above, this means editing /etc/ho8t8 and assigning each machine a host number — the 
last component of the entire address — under 1024. You can simply retain your old network 
number. Remember to install the /etc/ hosts file on all systems, and to reboot any machine 
whose host number you have changed. 

3. Finally, if you have machines that either cannot perform ARP (old Vaxen, for example), or 
cannot respond to ARP (older Sun systems with Class A networks and host numbers 
greater than 1024, for example), proceed as follows. 

You can allow machines which cannot perform ARP talk to a 1.1 network by 'forcing' your 
1.1 machines to respond to an address which non-ARPers understand. Do this by editing 
the /etc/rc.local file on each 1.1 machine, and adding an extra 'ifconfig' line with each 1.1 
machine's 'old' 6-byte hexadecimal Ethernet address: 

a) You can obtain this address for a 3COM Ethernet Board by using the PROM Monitor 
to interrogate the Multibus memory-space where the address is stored. As super-user, 
run the following sequence of commands (type < RETURN > where indicated): 

# /etc/fasthalt 
syncing disks . . . done 
Unix Halted 



> kl 

> e fe0400 

> FE0400: 

> FE0402: 

> FE0404: 



0260? <RETURN> 
SCOOT <RETURN> 
9920? q 



b) Then, edit the /etc/rc.local file, and add the following line, substituting the machine's 
entire 6-byte hexadecimal Ethernet address for old_ethernet_address: 

/etc/ifconfig ecO old_ethernet_addres» 'hostname' -trailers up 

For instance, the lines for the machine used in the example above might look like this: 

/etc/ifconfig ecO 'hostname' -trailers up 

/etc/ifconfig ecO 2:60:8C:0:99:20 'hostname' -trailers up 

c) Finally, reboot any machine whose file you have altered in this way. 

If you have machines that will not respond to ARP, you can use the /etc/ arp command to 
specify the Ethernet addresses for the machines (see arp(8)). 

6.2. Setting Up the Mail System 

The mail system consists of the following commands and files: 
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/bin/mail old standard mail program (from V7) 

/usr/ucb/mail UCB mail program, described in mail{l) 

/usr/lib/sendmail mail routing program 

/usr/lib/sendmail.cf configuration file for mail routing 

/usr/lib/sendmail.domain.cf configuration file for "main machines" (see belo-w) 

/usr/lib/sendmail.generic.cf configuration file for "subsidiary machines" (see below) 

/usr/spool/mail mail spooling directory 

/usr/spool/mqueue spool directory for mail going out over the network 

/usr/spool/secretmail secure mail directory 

/usr/bin/xsend secure mail sender 

/usr/bin/xget secure mail receiver 

/usr/lib/aliases mail forwarding information 

/usr/ucb/newaliases command to rebuild binary forwarding database 

/usr/ucb/biff mail notification enabler 

/usr/etc/in.comsat mail notification daemon 

/usr/etc/in.syslog error message logger, used by aendmail 

Special note for file server configurations: 

On file servers and diskless clients the directory /usr/lib resides on the shared, public disk. 
Since this disk is read-only and is shared by all the systems, files that need to be writable or 
need to be different on each machine cannot reside here. Instead there is a directory called 
/private that contains the files that would normally reside in /usr/lib. The setup program 
replaces the files in /usr/lib by symbolic links to the files in /private so the files can still be 
referenced by their normal names. The files (and directories) so affected are listed below: 

/usr/lib/sendmail.cf 

/usr/lib/aliases 

/usr/lib/aliases.dir 

/usr/lib/aliases.pag 

/usr/lib/crontab 

/usr/lib/uucp 

/usr/lib/news 

When the following instructions tell you to copy or edit one of the above files, instead use the 
corresponding file in /private. 

Mail is normally sent and received using the mail{l) command, which provides a front-end to 
edit the messages sent and received, and passes the messages to sendmail(S) for routing. The 
routing algorithm uses knowledge of the network name syntax, aliasing and forwarding informa- 
tion, and network topology, as defined in the configuration file /usr/lib/sendmail.cf, to process 
each piece of mail. Local mail is delivered by giving it to the program /bin/mail which adds it 
to the mailboxes in the directory /usr/spool/mail, using a locking protocol to avoid problems 
with simultaneous updates. After the mail is delivered, the local mail delivery daemon 
/usr/etc/in.comsat notices, and it notifies users who have issued a "biff y" command that mail 
has arrived. 

Mail for username is normally accessible in the file / usr/ spool/ mail/ username. In the distribu- 
tion system, your mail file is readable only by you; however, anyone with the super-user pass- 
word can read others' files, including their mail. To send mail which is secure against any possi- 
ble perusal (except by a code-breaker), use the secret mail facility, which encrypts the mail so 
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that no one can read it. See xsend{l). Note that this facility does not -work over the network. 

The following subsections give some instruction on tendmail installation; for more detailed infor- 
mation, see the Sendmail Installation and Operation Guide in the final section of this manual. 

6.2.1. Picking a Name for your Domain 

The network mail delivery program, sendmail, uses Internet standard mail addressing formats 
which make it possible for any Internet system in the world to send or receive mail with any 
other Internet system. To accomplish this, each system must have a unique name. To make it 
easier to assign names, the world of mail addresses is broken up into domains and subdomains. 

For example, many systems funded by the U.S. Government's Advanced Research Projects 
Agency are in the domain "arpa". Many of the systems which send mail via the uucp protocols 
are in the domain "uucp". Within each domain, names have to be unique — there can't be two 
machines called "MIT-Multics.arpa" or it would be impossible to decide how to deliver mail to 
them. 

Domains nest inside one another like directories, except that the names go from right to left. 
Thus "joe.sun.uucp" is host "joe" in subdomain "sun" which is in domain "uucp" just like 
"usr/lib/crontab" is file "crontab" in subdirectory "lib" in directory "usr". To make life easier 
for the people who maintain mailers, there are only a small number of "top-level" domains like 
"uucp" and "arpa". 

If your workstation is on the Arpanet, or shares an Ethernet with a machine on the Arpanet, or 
with a machine on the Arpa Internet, you should probably pick a name in the "arpa" domain, 
and register it with the Internet naming authority at the Arpanet Network Information Center. 
Otherwise, pick a name in the "uucp" domain. 

If your workstation and/or Ethernet have no phone lines or connections to other networks, the 
name you pick within the "uucp" domain doesn't matter much. You may, however, have to 
change the name if you get other network connections and somebody else is abeady using that 
name. 

If your organization already has hosts on the uucp network or the Usenet, ask a system adminis- 
trator for help in picking a name. 

If you are connected to the uucp network, you must be talking with at least one other computer 
on the network. Check with the system administrator of that machine to see if the name you 
have picked is already in use in the uucp network. If they are on the Usenet, they can look in 
newsgroup "net.map"; if not, they just have to guess. 

In a network of Suns, the name of the "main machine" becomes the name of your subdomain, 
and each other machine can truly have any name you want. For example, a main machine at a 
site might be called "fred"; various other machines on its Ethernet could be "shirl," "sal," etc. 
The fully qualified name of the "fred" machine is "fred.uucp" and must be unique in the uucp 
world; but the full name of "shirl" is "shirl .fred.uucp" and its uniqueness is guaranteed by the 
uniqueness of "fred.uucp" ". 

If you only have one machine, your host name and your domain name (within the "uucp" or 
"arpa" top-level domain) are the same. 
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6.2.2. Picking a "Main Machine" for Mail Forwarding 

To begin configuration, you must tell sendmail whether your system is the '^main machine'^ in a 
network, or a "subsidiary machine" in a network. 

If your machine is attached to an Ethernet and is also attached to phone lines, it is a "main 
machine". Pick one such machine on the network and make it your mail machine; treat all the 
rest as "subsidiary machines" for configuration purposes. Note that if you have a standalone 
system ( a machine which is not attached to an Ethernet), sendmail treats it like the "main 
machine" in a one-machine network. 

If your machine is attached to an Ethernet and you don't have any phone lines, but there is an 
Arpanet host on your Ethernet, you can pick any workstation as your "main machine". If your 
Arpanet host runs sendmail, it can be your "main machine". All the other Suns will be subsidi- 
ary machines. 

Similarly, if you have several machines on an Ethernet, and none of them have phones, pick one 
as the main machine and leave the rest as subsidiary machines. 

6.2.2.1. Configuring for Mail Forwarding 

Next, you must define each machine's mailer configuration. The following commands accom- 
plish this. Remember that if your machine is a file server or a diskless client, the sendmail.cf 
file is in / private/ sendmail.cf. 

To configure a "main machine": 

^ cp /usr/lib/sendmail.domain.cf /usr/lib/sendmail.cf 

To configure a "subsidiary machine": 

# cp /usr/lib/sendmail.generic.cf /usr/lib/sendmail.cf 



6.2.2.2. Telling Sendmail your Domain Name 

To tell sendmail ^h&t your domain is, edit the file /ttsrf lib/ sendmail.cf on the "main machine" 
and all the subsidiary machines. Remember that if your machine is a file server or a diskless 
client, the sendmail.cf file is in / private/ sendmail.cf. Near the top of the file is a block of lines 
that looks like this: 

# local domain names 

DDsun 

CDsun 

This defines our domain name as "sun" within the "uucp" domain — in other words, 
"sun.uucp". Change these lines to reflect the name you picked. For example, 

^ local domain names 

DDfred 

CDfred 

defines your domain name as "f red. uucp". The hostname of your main machine (as set up by 
the hostname command) is "fred," and subsidiary machines, if you have any, will be called (for 
example) "shirl.fred.uucp" for a machine whose hostname is "shirl". 
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If your top-level domain is not *'uucp", find the lines that look like: 

^ domain-spec for local domain within universe (e.g., what domains are above?) 

# should be integrated into mainline (e.g. Berkeley) config files 
DUuucp 

They should be the next thing in the file. Change "uucp" to your top-level domain name (for 
example, "DUarpa"). 

Now, if you are editing sendmaiicf tor a subsidiary machine, look for a block of lines like this: 

# major relay host 
DRmailhost 
CRmailhost 

Change the name "mailhost" to the name of your domain: 

# major relay host 
DRfred 

CRfred 

If you are editing sendmail.cf (or a subsidiary machine which has phone lines attached to it, you 
can have sendmail route uucp mail to certain hosts via the local phone lines, rather than having 
all uucp traffic go through the "main machine'\ To do this, find the lines that look like: 

i^ local UUCP connections ~ not forwarded to mailhost 
CV 

Put the names of the local uucp sites on the end of the "CV" line, or on additional CV lines. 
For example, 

CV rome prussia georgia 

This completes the sendmail.cf editing for the subsidiary machine. Note that if you have more 
than one subsidiary with no local uucp connections, you can edit the file just once and then 
copy it to all the subsidiary machines with rcp(l). 

On your main machine, you can make one optional change. If one of the machines with which 
you have a uucp or Ethernet connection is on the Arpanet and will relay mail for you, look for a 
block of lines like this: 

# major relay mailer 
DMuucp 

# major relay host 
DRucbarpa 
CRucbarpa 

Note that similar lines appear twice in the file — you should change the second set. Edit in the 
mailer that you connect to this host with ("uucp" or "ether") and the name of the relay host. 
For example, if you share an Ethernet with a machine called "cmu-cs-vlsi," which is on the 
Arpanet, your entry might look like this: 
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^ major relay mailer 
DMether 

# major relay host 
DRcmu-cs-vlsi 
CRcmu-C5-vlsi 

On the other hand, your relay point might be uucp host "ucbvax": 

^ major relay mailer 
DMuucp 

^ major relay host 

DRucbvax 

CRucbvax 

This change will let you mail to addresses like ^'charlieOmit-ai.arpa'^ and even though you 
aren't on the Arpanet, the message will get through. If you don't have an Arpanet relay point, 
don't worry about this. 

This completes the mailer configuration process. 

6.2.2.3. Setting up the ''Postmaster" Alias 

Edit the file /usr/ lib/ aliases (or /private/ aliases for a file server or diskless client workstation) 
and look for the entry for "postmaster". This is where people will send mail if they want to get 
in touch with someone at your site who can deal with mailer problems (you can send mail to 
"postmaster"s at other network sites if you have problems with mail that comes from there). 
The line will look like this: 

# Following alias is required by the new mail protocol, RFC 822 

^ Set it to the address of a HUMAN who deals with this system's mail problems 
Postm aster :root 

If you manage the mail system for your site, change the name "root" to the user name you usu- 
ally log in with, so that messages directed to the Postmaster of your machine will arrive with 
your usual mail. 

If you manage the mail system for several workstations, change the file on all of them to for- 
ward Postmaster mail to wherever you usually read mail. For example, if you are "henry" on 
machine "shirl," make the line read: 

Postmaster: henry ©shirl 

You can also create aliases for people or groups of people ("mailing lists") at this time. See the 
examples in the aliases file. You can edit this file now or at any later time. Each time you edit 
the file, run the newaliases program to rebuild the alias database with your changes. 
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6.2.3. Testing your Mailer Configuration 

The first thing to do is to reboot all the systems whose configuration files you have changed. 
Then, send test messages from various machines on the network with a command like this: 

hal% /usp/lib/sendmail -V </dev/null addresses 
hal% 

This will send a null message to the specified address, and display messages about what it is 
doing. Test that: 

• You can send mail to yourself, or other people, on the local machine, by addressing the 
message to a plain user name ('*root'\ for example). 

• If you have an Ethernet, you can send mail to someone on another machine (^'root©hobo,'' 
for example). Try this in three directions — from the main machine to a subsidiary 
machine, vice versa, and from a subsidiary machine to another subsidiary machine, if you 
have two. (Note that /etc/ hosts. equiv must be set up on at least the main machine before 
this will work. See the subsection. Handling Network Security with /etc/ hosts. equiv and 
/ .rhosts in the Installing UNIX for the First Time chapter.) 

• If you have a phone line and you have set up a uucp connection to another host, you can 
send mail to someone there and they can send it back (or call you on the phone, if they 
receive it). Try having them send mail to you. For example, you could send to 
''ucbvaxljoe" if you have a connection to ucbvax. Sendmail wonH be able to tell you 
whether the message really got through — since it just hands it oflf to uucp for delivery — 
so you have to ask a human at the other end. You might be able to get some idea of 
what's going on by looking in /usr/ spool/ uucp/ LOGFILE; see the Uucp Implementation 
Description in the Tutorials section of this manual. 

• Mail something to Postmaster on various machines and make sure that it comes to your 
usual mailbox, so when other sites send you mail as Postmaster, youVe sure you will see it. 

6.2.4. Diagnosing Troubles with Mail Delivery 

The best tools for diagnosis of mail problems are: 

• "Received'* lines in the header of the broken message. These give a trace of which systems 
the message was relayed through on its way. Note that in the uucp network there are 
many sites that do not update these lines, and that in the Arpanet the lines often get rear- 
ranged. You can straighten them out by looking at the date and time in each line. Don't 
forget to take time zones into account. 

• Messages from "MAILER-DAEMON" on various systems. These messages typically report 
delivery problems. More and more systems are producing these messages, rather than sim- 
ply throwing away mail that they can't deliver. 

• The system log, for delivery problems in your group of workstations. Sendmail records 
what it is doing all the time, and this information is kept in the system log. In the distri- 
buted system, the logs are kept for a week, then discarded. Log files are kept in 
/usr/ spool/log on your network server machine (the system log configuration is taken care 
of by the setup program during UNIX installation — see syslog(8)). Today's log is in file sys- 
log; the previous day's is syslog.O; two days' back is syslog.l, etc. If you have chronic trou- 
ble with mail, look at the log once in a while. At Sun, cron{8) runs a shell script nightly 
which searches the log for SYSERR messages and mails any that it finds to "Postmaster". 
This way, problems are often fixed before anyone notices them, and the mail system runs 
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more smoothly. 



6.3. System Log Configuration 

Various system daemons and programs record information in the system log to aid in problem 
analysis. They send this information as Internet datagrams directed to the 'syslog' daemon on 
host 'loghost'. The daemon receives these datagrams and records the information or notifies 
users of problems. See 8y8log{S) for more details on this process. 

The default configuration runs a syalog daemon on each machine, and also keeps all datagrams 
on the local machine (by maintaining the 'loghost' alias in the /etc/hosts entry for the local 
machine). If you are running standalone, this is how your system is configured. However, in a 
network environment it^s much easier to track problems if all machines log their information in 
a single place. Therefore, during first time UNIX installation, the setup program re-configures 
things so that only the designated server is the 'loghost': eetup strips the 'loghost' alias from 
the /etc/ hosts entries for the clients, and adds the alias for the server machine. This means 
that, for example, if the machine named krypton is your network server, the beginning of your 
machines* /etc/ hosts files might look like: 



192.9.1.1 


krypton loghost 


192.9.1.2 


wally 


192.9.1.3 


beaver 


192.9.1.4 


June 


192.9.1.5 


eldridge 



Now all datagrams sent to 'loghost' (from wally, beaver, etc.) are sent to krypton. There might 
also be other aliases on the same line of the /etc/ hosts entry, like 'Iprhost' or 'mailhost' — 
that's OK. Note also that, since the syslog daemon only starts up when messages must be han- 
dled, only the ioghost' runs the daemon. Getting rid of the daemon on all other machines frees 
up resources and makes the system start up faster. 

If you want to change this configuration — for example, if you have more than one server, and 
you want only one ioghost' — simply change the placement of the ioghost' alias, and then re- 
copy /etc/ hosts to all machines. Test your system log configuration by running: 

% tail -f /usr/spool/log/syslog 



on the loghost machine, then sending any kind of mail on the various other machines, 
message sent will generate four or five lines of output if things are working. 



Each 



6.4. Setting Up a UUCP Connection 

uucp (UNDC to UNIX copy) is a series of programs designed for communication, via dial-up or 
hardwired lines, between two systems running UNIX, uucp may be used to transfer files between 
UNIX systems, and also to run commands on remote machines. For more detailed background, 
see the UUCP Impiementation Description in the Tutorials section of this manual. 

Support for uucp is located in three major directories: /usr/bin (which contains user commands), 
/usr/lib/uucp (operational commands), and /usr/ spool/ uucp (spooling area). 
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The commands in /usr/bin are: 



/usr/bin/uucp 

/usr/bin/uux 

/usr/bin/uusend 

/usr/bin/uuencode 

/usr/bin/uudecode 

/usr/bin/uulog 



file-copy command 
remote execution command 
binary file transfer using mail 
binary file encoder (for uusend) 
binary file decoder (for utiaend) 
scans session log files 



The important files and commands in /usr/lib/uuepdxe: 



/usr/lib/uucp/L-devices 

/usr/lib/uucp/L-dialcodes 

/usr/lib/uucp/L .cmds 

/usr/lib/uucp/L .sys 

/usr/lib/uucp/SEQF 

/usr/lib/uucp/USBRFILE 

/usr/lib/uucp/uucico 

/usr/lib/uucp/uucp.day 

/usr/lib/uucp/uucp.hour 

/usr/lib/uucp/uucp.night 

/usr/lib/uucp/uucp.noon 

/usr/lib/uucp/uucp.week 

/usr/lib/uucp/uupoU 

/usr/lib/uucp/ unclean 

/usr/lib/uucp/uuxqt 



list of dialers and hardwired lines 

dialcode abbreyiations 

commands remote sites may execute 

systems to communicate with, how to connect, and when 

sequence numbering control file 

remote site pathname access specifications 

uucp protocol daemon 

script for daily polling/cleanup 

script for hourly polling 

script for nightly polling 

script for midday polling 

script for weekly cleanup of uucp log files 

site-polling script 

cleans up garbage files in spool area 

uucp remotej^execution server 



The spooling area, juar/ spool/ uucp, contains the following important files and directories: 



/usr/spool/uucp/C. 
/usr/spool/uucp/D. 
/nar/spool/xkucp/D. hostname 
/usr/spool/uucp/LOGFILE 
/usr/spool/uucp/SYSLOG 



directory for command, **C." files 
directory for data, "D.", files 
directory for local "D." files 
log file of uucp activity 
log file of uucp file transfers 



Note that C, t)., and D. hostname are subdirectories, unlike earlier implementations of uucp. In 
older versions, C. and D. files are placed directly into the spooling directory, /usr/ spool/ uucp; in 
the current version, they are placed in their appropriate subdirectory. So, in the old version 
you'd have, say, /usr/ spool/ uucp/ C.res^SnOOSl', in the new version the file would be 
/usr/ spool/ uucp/ C./ C.res45nOOSl. 

As uucp operates it creates (and removes) many small files in the directories underneath 
/usr/ spool/ uucp. Sometimes files are left undeleted; these are most easily purged with the 
uuclean program. Instructions in the uucp. day file take care of doing this daily clean-up for you. 
The uucp log files can grow without bound unless trimmed back; uulog is used to maintain these 
files, uucp. day and uucp. week manage this housekeeping. If you decide to prune these direc- 
tories yourself, be careful: randomly removing files from /usr/ spool/ uucp may cause uucp to gen- 
erate error messages when it tries to access a file another file claims is there. (For instance, each 
mail transaction creates three files.) You do, however, need to clean the / usr/ spool/ uucppublic 
directory 'manually'; this is a place for people at other sites to send to when sending files to 
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users at your site. 

uucp occasionally sends mail about minor problems to "uucp" or "root". Your maintenance 
person should also read and toss these messages. You can redirect the mail to your mailbox by 
putting an entry for "uucp" in /usr/ lib/ aliases. Look at the examples there. 

Under normal conditions, uucp calls your designated sites at specified times and, Tvhile it's at it, 
checks to see if anything should come back. If you ever need to invoke uucp 'on command^ the 
line: 

# /usr/lib/uucp/uucico -rl -Bsitename 

forces uucp to poll sitename, even if there is nothing waiting. If you do run uucp in this fashion, 
don't run it as super-user, since the suid* bit yfiW not be honored. If you are having trouble with 
the connection, run uucp with the debugging option, as described in installation step 7, below. 

6.4.1. L/^t/CF Installation Overview 

A uucp network link using modems or dedicated lines may be established between two machines 
running UNIX systems. To establish a connection between two sites that both have modems, 
one site must have (at least) an automatic call unit (an auto-dial modem) and the other must 
have (at least) a dialup port (an auto-answer modem). It is better if both sites have one of each 
or, as is standard, have modems which both call and answer, like Ventel's. 

If both you and the site(s) you wish to connect with have autodial units and ports, install uucp 
as follows. If you have only a dialup your situation will be different; procedures are described 
near the end of this section. For more information, read the Uucp Implementation Description 
in the final section of this manual. It describes in detail the file formats and conventions, and 
will give you necessary context. 

1. Select a site name (less than 8 characters): the name of the machine which will be your 
uucp connection to the outside world. We will call this machine your ^uucp host'; its name 
is your ^uucp hostname'. 

If this machine is your "main machine" (see Setting Up the Mail System, above), then your 
uucp hostname should be the same as your domain name. 

2. Change the f usr/ spool/ uucp/ D.noname directory to your own site's 
/ usr / spool/ uucp/ D .hostname directory with the following: 

# mv /usr/spool/uucp/D.noname / usr /npool/ uucp /"D. hostname 
Use your uucp hostname for hostname. 

3. Create a uucp account in the password file on your uucp host machine by entering a line of 
the following form in / etc/ passwd: 

\Jhostname:*t4i4:i/uBT/Bpoo\/uucpt/uBT/\ih/uucp/uucico 

Now use the passwd command to establish a password for your host: 

# passwd XJhostname 



* "suid" stands for "set user i.d."; if you set this bit on an executable file, UNDC will grant or deny 
file access based on the permissions of the file's owner, rather than the permissions of the person 
who executes the file. Uuep uses this facility to ensure that all the files in its spool directories are 
readable and writeable no matter who invokes the uuep program. 
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4. The L.sya file contains the phone numbers and login sequences required to establish a con- 
nection with a uuep daemon on another machine. Edit /u»r/lib/uitcp/L.syt, adding a line of 
the following form for each site you want to talk to: 

their Jiost Any device baud phone^ login :-EOT-login: uucp ssword: pass 

The first field is the uucp hostname of the other site, the second indicates when their host 
may be called, the third field specifies how their host is connected (through an ACU, a 
hardwired line, etc.), then comes the baud rate of the line, phone number to use in connect- 
ing through an auto-call unit, and finally a login sequence. The phone number may contain 
common abbreviations which are defined in the L-dialcodes file. The device specification 
(third field) should refer to devices specified in the L' devices file. Note that the only 
modem type currently supported by Sun Microsystems is the Ventel MD212 modem. Indi- 
cating only ''ACU" causes the uucp daemon, uucico, to search for any available auto-call 
unit in L'devices. For example, our L.sys file looks something like: 

adiron Any ACUVENTEL 1200 7620883 lo^n:-EOT-login: uucp ssword: secret 
ucbvax Any,20 ACUVENTEL 1200 6728212% login:-EOT-login: uucp ssword: almama 
ucbarpa Any,20 ACUVENTEL 1200 6424351 login:-EOT-login: uucp ssword: netnut 
decvax Any ACUVENTEL 1200 6039941241 login:-EOT-login: Ujedi ssword: cannon 

For hardwired lines, your L.sya lines should contain the tty device name in the third and 
fifth fields: 

anyname Any ttyb 1200 ttyb Io^n:-EOT-lo^n: uucp ssword: sunrise 

5. Connect your (auto-dial/auto-answer) modem to ttya (the port labelled 'RS-232-A' on the 
backpanel of your Sun Workstation) on your host machine. 

6. Create the appropriate device for your modem with the following series of commands: 

# cd /dev 

# mknod cuaO c 12 128 
- # In ttya c «a^ — 

# chmod 600 cuaO 
^ chown uucp cuaO 
#Jli<UtyattydO 

7. Edit /etc/ttys to include an entry for ttydO (see ttys(i)). Insert the line: "13ttyd0". Then 
type the following to initialize everything properly: 

# kill >1 1 

8. Make sure your modem is hooked up properly by running tip with the phone number of a 
known machine: 

# tip 6423345 

If you get a "dialing . . . connected" response, all is well. If you get any other response, 
reconnect your modem. 

9. As a final test, run uucp with the debug option (— x), as follows: 

# /usr/lib/uucp/uucico -rl -ssitename -x7 

With the -X option, the higher the number, the more debugging output you get; 1, 4, and 7 
are reasonable choices. If you get immense quantities of output from this command, every- 
thing is fine; you can go on to edit the following files. 
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10. Edit the files uucp.day, ttucp.noon, and uucp.night, in the /usr/lib/uucp directory. Each of 
these files has a 'for* loop which arranges to call sites you want to call at designated times 
for mail. In each file, find the line that says: 

for i in sys.name 

and change "sys.name" to the site name(s) you want to poll. For example: 

for i in ucbvax ucbarpa Shasta navajo 

11. Add the uucp.day, uuep.noon, uuep.night, uttcp.hour, and uucp.week, files to /usr/lib/crontab 
(see cron{8)), which arranges for the appropriate sites to be polled at the appropriate times. 
For example, the entries in crontab might look like: 

5 6 * * ♦ su uucp < /usr/lib/uucp/uucp.day 
15 12 * * * su uucp < /usr/lib/uucp/uucp.noon 
30 23 * * * su uucp < /usr/lib/uucp/uucp.night 
10,30,50 * * * * su uucp < /usr/lib/uucp/uucp.hour 
7 * * 2 su uucp < /usr/lib/uucp/uucp.week 

If you have only a dialup, you can be a second-class citizen on the uucp net. You must find 
another site that has a dialer, and have them poll you regularly (once a day is. about the 
minimum that is reasonable). When you send mail to another site, you must wait for them to 
call you. To handle installation for a passive node, just complete steps one through four in the 
procedures above. When you come to the final step, editing /usr/ lib/ uucp/ L.sys, you don't 
need to specify all the information called for in the step: only the first two fields of L.sys are 
necessary, and in practice only the first field (site name) is looked at. A typical L.sys for a pas- 
sive node might be: 

ucbvax None 
research None 

where the first field on each line is a site that will poll you. Next, put a password on the uucp 
login. Then let the other site know your phone number, uucp login name, and password. 

6.5. USENET Installation /Conversion 

This section is intended to help a new USENET site install the network news software, and to 
give conversion guidelines to sites currently running USENET version 2.9. The news software 
is publicly available over the USENET; the news system released with the Sun 1.0 and the 
current software distribution is a Sun-supported version of USENET version 2.10.1. For more 
information on installation and maintenance (information on files, setting up links, control mes- 
sages, maintenance of the news system, and how to create new newsgroups), see the USENET 
Installation and Maintenance paper in the Tutorials section of this manual. 

6.5.1. USENET Installation 

The overall order of things to do is: 

1. Find somebody to link up with. You need a network connection of some kind — most 
likely, uucp. If you use uucp and have no connections, you must have at least a dialup and 
preferably a dialer, and find someone willing to call your machine. You can use the 
USENET directory to locate some other site near yours to hook up to. 
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2. Edit the /usr/ lib/ news/ sy» file, adding an entry for the site(s) you wish to connect to, and 
an entry for your own site. Sys is similar to the uucp L.sys file: it lists all your neighbors, 
which newsgroups they subscribe to, and describes how to send news to them. The format 
of the sys file is as follows: 
Each line of sys contains four fields; fields are separated by colons: 

(1) The system name of a site to which you forward news. Normally, you should include a 
line for all systems you have links to, as well a line for your own system. 

(2) The newsgroups to be forwarded to them. This is a pattern in the sense of a subscrip- 
tion. Generally, you will list classes of newsgroups, that is, using all for everything. A 
typical forwarding list for a new site would be: 

net . all ,f a. all ,t csysname 

where sysname is the name of your contact site. Note that you should not forward all, 
in particular, since local newsgroups (those without dots) should not be sent. In the 
line describing your own system, this field describes the newsgroups your site will 
accept from contact sites. Thus, if another site insists on sending you a newsgroup you 
don't want, say netjokes, include Inetjokes here. 

(3) Flags describing the connection between sites. These are: 

A Indicates that the contact site is running an A version of netnews, or 

B The contact site is running a B version. If neither A nor B is indicated here, 
default is B. If you are running the latest release of Sun software, you have a B 
version. If you aren't sure which version your contact site is running, ask them 
before proceeding. 

F Indicates that the fourth field is the name of a file. The full path name of a file 
containing the article in /usr/ spool/ news will be appended to this file. 

L Prevents transmission unless the article was created on this site. Feeding an L link 
to a backbone site ensures that your submissions will be more likely to get to the 
entire network, even in the event of a local problem. Please make sure that a mail 
link exists too, so you can get replies. 

U Arranges that the parameter to the optional %s in the command field be filled in 
with a permanent file name from /usr/ spool/ newt instead of a temporary custom- 
ized file name. 

(4) The command to be run to send news to the remote site. The article will be on the 
standard input. A %s in the command will be replaced with the name of the file that 
contains the article. Leaving this field blank means an ordinary uucp link is being 
used; that is, the command defaults to: 

uux - — r — z sfjinamelTnewa 

Options here are: 

— Tells uux to expect input on stdin. 

~r Tells uux not to start up a daemon right away. This eases the load on the system, 
and makes news transmission only a bit slower. News is sent when the next dae- 
mon is started, usually the next time uucico is invoked by cron. 

—I Shuts off the annoying message you would otherwise get mailed to you telling you 
that your article was successfully broadcast. The — z option is nonstandard; the 
remote system may need to be modified to understand it. To avoid using — z, put 
the uux command in the fourth field. 
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Here is a sample sys file for a site "zenith" with connections to "nadir". "Zenith" also 
passes news on to "lowerreaches". We assume that "zenith" and "lowerreaches" 
exchange a local newsgroup class Ing.all as well as the network wide newsgroups. 

zenith:net.all,fa.all,lng.all:: 

nadir:net.all,fa.all:: 

lowerreaches:net.all,fa.all,lng.all:: 

3. After adding the site you want to connect to to your sys file, have your contact at the 
other end of the link add you to their sys file. 

4. Have the site you want to connect to send you their active file, and use the makeactive.sh 
shell script to create your local directory hierarchy and active file. 

Active lists active newsgroups. The order of the list dictates the order in which news will be 
presented by readnews, so you might want to edit active later and arrange the newsgroups 
accordingly. 

Each line of the active file contains two fields: the newsgroup name, and the highest local 
article number (for the most recently received article). The fields are separated by a space. 
Initially, your local active file will have 00000 as the article number for each newsgroup; 
local article numbers begin at 1 for the first article received in each group and increment 
within the newsgroup as articles are received. They do not usually correspond to local arti- 
cle numbers at other sites. The article number is always stored as a 5 digit number (with 
leading zeros) to allow updating of the file in place. 

Active is automatically updated as new newsgroups come in. For information on how to 
create new newsgroups, see the Creating New Newsgroups section of the USENET Installa- 
tion and Maintenance paper in the final section of this manual. 

5. Post a message to the to,sysname newsgroup — which should be set up to go only to the 
site you are linked to — as a test (please don't use net.test unless there is no alternative. 
It is almost always possible to use test, or to,sysname, or some local.test group, instead 
of net.test). Have your contact send a message to your system using the same mechanism. 
If this doesn't work, find the problem and fix it. 

6. Fill out a USENET directory form and post a copy to the USENET newsgroup 
net.news.newsite. 

7. Post the etiquette and tencmdts files (in the /usr/ lib/ news/ doc directory) to your general 
newsgroup with a long expiration date. Running rnews separately on each of these files will 
do. 

6.5.2. Conversion from USENET Version 2.9 to 2.10 

In this section, we give procedures for converting from version 2.9 (released with the Sun 0.4 
and earlier software distributions) to version 2.10 (released with the Sun 1.0 and current distri- 
butions) of the USENET software. 

There are some incompatiblities between 2.9 and 2.10. None of them should cause a problem, 
but you should be aware of them. For a discussion of the differences between the versions, see 
the paper in the Tutorials section of this manual, USENET Installation and Maintenance. 

Overall recommended conversion order: 

1. Become user "news": 
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hackster% su 

Password: 

SU: shannon /dev/console 

hackster# su news 

hackster% 

2. Restore your /uar/ spool/ news hierarchy and the following files from /uar/ lib/ news: active, 
sys, history. 

3. Check your /usr/ lib/ news/ active file and clean out any duplicates and old newsgroups. 

4. Make the new spool directories: 

hackster% cd /usr/lib/news/cvt 

hackster% sh cvt.mkdirs.sh /usr/lib/news /usr/spool/news 

5. Convert the history file: 

hackster% cc cvt.hist.c -Idbm 
hackster% a.out /usr/lib/news 

6. Convert the active file: 

hackster% sh cvt.active.sh /usr/lib/news /usr/spool/news 

7. Make links to spooled articles (this takes some time): 

hackster% sh cvt.links.sh /usr/lib/news /usr/spool/news 

8. Clean out the old spool hierarchy: 

hackster% sh cvt.clean.sh /usr/spool/news 

Several shell scripts and C programs are provided (in the directory /usr/lib/news/cvt) to help 
with this conversion. The above scripts will convert active and create the new directory tree. 
The final script removes the old dot files and directories. 

After the conversion, you should create two new newsgroups: junk and control. Junk is for 
messages that are in an invalid newsgroup (so you can see what^s getting thrown away). Con- 
trol is for control messages. Ordinaa-y users probably won't want to read either, but as 
administrator you might want to. To create them: 

hackster% mkdir /usr/spool/news/junk /usr/spool/news/control 

and add the following two lines to the end of / usr/ lib/ news/ active: 

junk 00000 
control 00000 
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0.6. Setting Up the Line Printer System 

The line printer system consists of at least the following files and commands: 

/usr/ucb/lpq spooling queue examination program 

/usr/ucb/lprm program to delete jobs from a queue 

/usr/ucb/lpr program to enter a job in a printer queue 

/etc/printcap printer configuration and capability data base 

/usr/lib/lpd line printer daemon, scans spooling queues 

/etc/lpc line printer control program 

The file /etc/printcap is a master data base; it describes line printers directly attached to a 
msM^hine and printers accessible across a network. The manual page prtnteap{S) describes the 
format of this data base and also indicates the default values for such things as the directory in 
which spooling is performed. The line printer system handles multiple printers, multiple spool- 
ing queues, local and remote printers, and printers attached via serial lines which require line 
initialization such as baud rate. Raster output devices such as a Varian or Versatec, and laser 
printers such as an Imagen, can also be handled by the line printer system. 

Remote spooling via the network is handled with two spooling queues, one on the local machine 
and one on the remote machine. When a remote printer job is initiated with Ipr, the job is 
queued locally and a daemon process is created to oversee the transfer of the job to the remote 
machine. If the destination machine is unreachable, the job will remain queued until it is possi- 
ble to transfer the files to the spooling queue on the remote machine. The Ipq program shows 
the contents of spool queues on both the local and remote machines. 

6.6.1. Printer Configuration 

You may connect a line printer with a serial interface to one of the serial ports on the Sun 
Workstation backpanel. Although this release of Sun software also supports the Centronics and 
Versatec interfaces provided by the Systech board, the following section is geared only to 
printers with serial interfaces. 

The basic procedure for configuring a line printer into the system is described in the following. 
For more detail — or if you have problems — refer to the Line Printer Spooler Manual in the 
Tutorials section of this manual. 

1. Attach a line printer with a serial interface to one of the serial ports on the workstation 
backpanel. Models 100U/150U and 120 provide ports A and B; if you have a Sun-2/120 or 
Sun-2/170 with a SCSI Interface, ports SIO-SO, SIO-1, SI0-S2, and SI0-S3 are also avail- 
able. 

2. The next step is to make sure that init{S) does not create a login process on the port you 
are using for your printer when the system comes up multi-user. Do this by editing the 
/etc/ttys file. Verify that the entry for the port (ttya, ttyb, etc.) has a zero as the first char- 
acter on the line. For example, if you are using serial port A for your line printer, the first 
few Hues in /etc/ttyt might look like- 
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12console 

02ttya 

02ttyb 

02ttym0 

02ttyml 

02ttym2 

02ttym3 

[ etc. ] 

3. If you had to change /etc/ttya in step 2, run the following command (as super-user) aftei> 
wards to bring the changes into effect: 

% kill -1 1 

4. Check the following files by using a ''Is -Igd" command, and verify that permissions, 
owner, and filename are the same as this list: 

-rws-s-x 1 root daemon 57344 Oct 20 13:35 /usr/lib/lpd 
-rws-s~x 1 root daemon 30720 Oct 20 13:35 /usr/ucb/lpr 
drwxrwx — 2 daemon daemon 512 Oct 29 12:32 /usr/spool/lpd 

5. Next, edit the /etc/prmtcap file to add an entry for your printer. Here are a few sample 
printcap entries for various printers/plotters: 

# 

# Dec Writer over a tty line. 
lp|ap|arpa|ucbarpa|LA-180 DecWriter III:N 

:br#1200:fs#06320:tr=of=/usr/lib/lpf:lf=/usr/adm/lpd-errs: 

# typical remote printer entry 
ucbvax|vaxjvx(ucbvax line printer:N 

:lp»-:rm=»ucbvax:sda»«/usr/spool/vaxlpd:lf««/usr/adm/lpd-errs: 

All of the above fields are explained on the prmtcap{B) manual page. For more information 
on the entries for printers on serial lines and remote printers, see the Line Printer Spooler 
Manual in the Tutorials section of this manual. 

6. Most printer characteristics can be specified in /etc/ printcap, but not all; you may need to 
use stty(l) or an output filter. Output filters and filter specifications are discussed in the 
Line Printer Spooler Manual. 

When you have completed these 5 steps, you can test the interface by printing a random file: 

% Ipr random 
Wait a minute or two; if you get no response, consult the next section. 

6.6.2. Line Printer Troubleshooting 

If you have followed the steps in the previous section and the Ipr command doesn't work, con- 
sider the following: 

1. Run the printer's stand-alone diagnostics. If these don't run, consult the operation manual 
for the printer or contact the printer manufacturer. 

2. Verify that the printer switch settings are correct. Check for the correct settings in the 
printer operation manual. 
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3. Try setting the terminal characteristics using stty{l) followed by a cat{l) of a file to 
/dev/ttyx, where x is the serial port the printer is attached to. For example: 

% (stty 1200; cat /etc/passwd)> /dev/ttyx 

If the printer is "dead", your RS-232 cable may be bad, or you may need a null modem 
cable. See the section entitled Asynchronous Serial Ports in the Hardware Configuration 
and Expansion chapter for wiring information on RS-232 and null modem cables. 

If the printer is responding but output is garbled, the terminal characteristics may be set 
incorrectly. Again, look at the output filter code to see what is done there. 

4. If the cat{l) experiment above works, but Ipr doesn't, it may be that a file is not found, or 
has incorrect permissions, etc. Check the characteristics of the /pr-related files according to 
the instructions above. Make sure that your output filter (if you only have one) is execut- 
able and that it is where you say it is. Check other /etc/printcap entries to make sure they 
are correct. 

5. If you are getting error messages, see the Line Printer Spooler Manual for interpretation. 

6.7. Adding Users 

New users can be added to the system by adding a line to the password file /etc/passwd. The 
procedure for adding a new user is described in adduser{S). 

You should add accounts for the initial user community, giving each a directory and a pass- 
word, and putting users who will wish to share software in the same groups. 

6.8. Bootstrap and Shutdown Procedures 

In a normal reboot, the system checks the disks and comes up multi-user without intervention 
at the console. Such a reboot can be stopped (after it prints the date) with a 'C (interrupt). 
This will leave the system in single-user mode, with only the console terminal 2K;tive. 

If booting from the console command level is needed, then the command: 

> b 

boots the system from the default device. 
You can boot to single user mode with: 

> b-8 

For a more complete discussion of booting — for example, how to boot from specific devices — 
see the appendix to this manual: Power-up and Bootstrap. 

To take the system down to a single user state you must be super-user. Then you kill all active 
processes with: 

# kill 1 

or use the / etc/ shutdown(8) command (which is much more polite, if there are other users 
logged in) when you are up multi-user. Either command kills all processes and gives you a shell 
on the console, as if you had just booted single-user. Previously mounted file systems remain 
mounted after the system is taken single-user. If you wish to come up multi-user again, you 
have to change directory to root, unmount all mounted file systems, then log out of single-user 
state: 
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#cd/ 

^ /etc/u mount —a 

# 'D [ Brings the system up multi-user ] 

Each system shutdown, crash, processor halt and reboot is recorded in the file 
/usr/adm/ahutdownlogv/'ith. the cause. 

6.9. Device Errors and Diagnostics 

When errors occur on peripherals or in the system, the system prints a warning diagnostic on 
the console. These messages are collected regularly and written into a system error log file 
/ uer/ adm/ messages by dmesg{8), which is started by cron(S). 

Error messages printed by the devices in the system are described with the drivers for the dev- 
ices in the Section 4 pages of the System Interface Manual. If errors occur indicating hardware 
problems, you should contact your hardware support group or field service. It is a good idea to 
examine and truncate the error log file regularly — see the section below on Files which Need 
Periodic Attention. 

0.10. File System Checks, Backups, and Disaster Recovery 

Periodically (say every week or so in the absence of any problems) and always (usually automat- 
ically) after a crash, all the file systems should be checked for consistency by /etc/fsck (see 
fsck{l)). The procedures of /etc/reboot (see reboot{S)) should be used to get the system to a 
state where a file system check can be performed manually or automatically. 

Dumping of the file systems should be done regularly, since once the system is going it is easy to 
become complacent. Complete and incremental dumps are easily done with /etc/ dump (see 
dump{8)). Most people do a level-0 dump on a weekly or monthly basis, and a level-9 dump 
daily. 

Dumping files by name is best done by tar{l), but the amount of data that can be moved in this 
way is limited to a single tape. 

It is desirable that full dumps of the root file system be made regularly. This is especially true 
when only one disk is available. Then, if the root file system is damaged by a hardware or 
software failure, you can rebuild a workable disk by doing a restore in the same way that the 
initial root file system was created. 

In the normal nature of things, disk space gets used up until your /usr file system is full. At 
this point, there are several places to look for files you can remove: 

• Every time a crash occurs, several MBytes of system image get dumped into the /usr/ crash 
directory. You can clean the vm* files out if you don't need them for debugging or trouble 
reporting. Don't remove the / usr/ crash/ bounds G\e. 

• Files in /usr/adm grow and must be pruned regularly. 

• Check your accumulated mail file(s) — some diligent mail writers have been known to gen- 
erate about a quarter of a MByte of mail per user per month. 

• Network news accumulates at a fearsome rate. 

• Finally, police your own directories regularly. 

Useful mechanisms for monitoring disk usage are du{l) and df{l). 
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6.11. Moving Filesystem Data 

If you have the equipment, the best way to move a file system is to dump it to magnetic tape 
using /etc/ dump (see </ump(8)), use /etc/newfs (see newfs{S)) to create the new file system, and 
restore the tape, using /etc/restore (see re«fore(8)). If for some reason you don't want to use 
tape, dump accepts an argument telling where to put the dump; you might use another disk. 
The restore program uses an "in-place" algorithm which allows file system dumps to be restored 
without concern for the original size of the file system. Further, portions of a file system may 
be selectively restored in a manner similar to the tape archive program. If you have to merge 
one file system into another, the best bet is to use (ar(l). If you must shrink a file system, the 
best bet is to dump the original and restore it onto the new file system. 

Note that a level zero dump must be done after a full restore, because the restore relocates the 
files, although it does not change their content. Thus, you must do another level zero dump to 
get a tape image refiecting the new file positions, so that later incremental dumps will be 
correct. 

6.12. Monitoring System Performance 

The vmatat program provided with the system is designed to be an aid to monitoring system- 
wide activity — see vm8tat(8). Together with the ps{l) command (as in "ps av"), it can be used 
to investigate systemwide virtual memory activity. By running vmstat{S) when the system is 
active you can judge the system activity in several dimensions: job distribution, virtual memory 
load, paging and swapping activity, disk and cpu utilization. Ideally, there should be few 
blocked (b) jobs, there should be little paging or swapping activity, there should be available 
bandwidth on the disk devices (most single arms peak out at 30-35 tps in practice), and the user 
cpu utilization (us) should be high (above 60%). 

If the system is busy, then the count of active jobs may be large, and several of these jobs may 
often be blocked (b). If the virtual memory is active, then the paging daemon will be running 
(sr will be non-zero). It is healthy for the paging demon to free pages when the virtual memory 
gets active; it is triggered by the amount of free memory dropping below a threshold and 
increases its pace as free memory goes to zero. 

If you run vmstat{S) when the system is busy (a "vmstat 1" gives all the numbers computed by 
the system), you can find imbalances by noting abnormal job distributions. If many processes 
are blocked (b), then the disk subsystem is overloaded or imbalanced. If you have several non- 
DMA devices or open teletype lines that are "ringing", or user programs that are doing high- 
speed non-buffered input/output, then the system time may go high (60-70% or higher). It is 
often possible to pin down the cause of high system time by looking to see if there is excessive 
context switching (cs), interrupt activity (in) or system call activity (sy). 

If the system is heavily loaded, or if you have little memory for your load, then the system may 
be forced to swap. This is likely to be accompanied by a noticeable reduction in system perfor- 
mance and pregnant pauses when interactive jobs such as editors or window system programs 
swap out. If you expect to be in a memory-poor environment for an extended period you might 
consider administratively limiting system load. 
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6.13. Making Local Modifications 

Locally written commands are kept in /usr/src/hcal and their binaries are kept in /usr/local. 
This allows /usr/bin, /usr/ucb, and /bin to correspond to the distribution tape (and to the sys- 
tem manuals). People wishing to use /usr/loccJ commands should be made aware that they 
aren^t in the base manual. 

A /««r/yunife directory to throw garbage into, as well as binary directories /ti«r/o/(/ and /uar/new 
are useful. The man command supports manual directories such as /usr/man/manj for junk 
and / usr/ man/ mani for local manual page entries to make this or something similar practical. 

6.14. Accounting 

Optionally, UNDC records two kinds of accounting information: connect-time accounting and 
process-resource accounting. Connect-time accounting information is stored in the 
/ usr/ adm/ wtmp file, which is summarized by the program /etc/ac (see ae(S)). Process-time 
accounting information is stored in /u»r/adm/acct, and analyzed and summarized by the pro- 
gram /etc/aa (see «a(8)). 

If you need to charge for computing time, you can implement procedures based on the informar 
tion provided by these commands. A convenient way to do this is to give commands to the 
clock daemon /ctc/cron to be executed every day at a specified time. This is done by adding 
lines to /utr/lib/crontab; see cron{S) for details. 

6.15. Resource Control 

Resource control in the current version of UNIX is rather primitive. The resources consumed by 
any single process can be voluntarily limited by the mechanisms of aetrlimit{2). Disk space 
usage can be monitored by du{l). No system-enforced procedure for controlling a user's disk 
space usage is implemented under the current system, although a modicum of control can be 
obtained by dividing user groups between different disk partitions. 

6 .Id* Network Troubleshooting 

If you have anything more than a trivial network configuration, from time to time you are 
bound to run into problems. Before blaming the software, first check your network connections. 
On networks such as the Ethernet a loose cable tap or misplaced transceiver cable can result in 
severely deteriorated service. The net3tat{S) program may be of aid in tracking down hardware 
malfunctions. In particular, look at the — i and —a options on the manual page. 

If you believe you have a faulty coaxial Ethernet cable, test the cable to make sure it is deliver- 
ing 50 ohms: remove the terminator from the N-connector on the transceiver terminating the 
cable, and use an ohm meter to test resistance (use the pin 'inside' the N-connector for signal, 
and the housing as ground). If you are getting something other than 50 ohms, your cable may 
be damaged. Contact Sun Microsystems for assistance. 

If you believe the routing daemon is malfunctioning, its actions — and even all the packets sent 
and received — may be printed out. To create a log file of routing daemon actions, just supply 
a file name when you start the daemon up, for example: 

# /etc/routed /etc/routerlog 
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Whenever a route is added, deleted, or modified, a log of the action and a history of the previ- 
ous packets sent and received will be printed in the log file. To force full packet tracing, the — t 
option may be specified when the daemon is started up. Beware though — on a busy network 
this will generate almost constant output. 



6.17. Files which Need Periodic Attention 

The following files require periodic attention or are system-specific: 



/etc/fstab 

/etc/printcap 

/etc /remote 

/etc/group 

/etc/motd 

/etc/passwd 

/etc/rc. local 

/etc/hosts 

/etc/networks 

/etc /services 

/etc/hosts .equiv 

/etc/securetty 

/etc/ttyy 

/etc /tty type 

/usr/lib/crontab 

/usr/lib/aliases 

/usr/adm/acct 

/usr/adm /messages 

/usr/adm/shutdownlog 

/usr/adm/wtmp 



how disk partitions are used 

printer data base 

names and phone numbers of remote machines for tip(l) 

group memberships 

message of the day, printed at login 

password file; each account has a line 

local system restart script; runs reboot; starts daemons 

host name data base 

network name data base 

network services data base 

hosts under same administrative control 

restricted list of ttys where root can log in 

enables/disables ports 

terminal types connected to ports 

commands that are run periodically 

mail forwarding and distribution groups 

raw process account data 

system error log 

log of system reboots 

login session accounting 
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Upgrading System Software 



This chapter outlines procedures for upgrading software to a new release level. 

7.1. gtep 1: What To Save 

No matter what version of the system you may be running, you will have to rebuild your root 
and jusr file systems. The easiest way to do this is to save the important files on your existing 
system, perform a bootstrap as if you were installing a software release on a brand new 
machine, then merge the saved files into the new system. The following lists the standard set of 
files you will want to save (in addition to all user files) and indicates directories in which 
site-specific files should be present. This list will probably be augmented with non-standard files 
you have added to your system; be sure to do a tar of the directories Ittcj, /lib/, and /uar/lih/ 
so that you don't miss anything the first time around. 

Table 7-1: Standard List of Files to Save when Upgrading 



/.profile 

/.login 

/.cshrc 

/.rhosts 

/dev/MAKEDEV.local 

/etc/fstab 

/etc/gettytab 

/etc/group 

/etc /hosts 

/etc/hosts.equiv 

/et'C/nd. local 

/etc/networks 

/etc/passwd 

/etc/printcap 

/etc/rc 

/etc/rc .local 

/etc/remote 

/etc/ttys 

/etc/ttytype 

/etc/termcap 



root sh startup script 

root csh startup script 

root csh startup script 

list of hosts/users trusted at the superuser level 

for the LOCAL case for making devices 

disk configuration data 

tty port speeds database 

group database 

hosts database 

list of trusted hosts on your network 

network disk local initialization file 

list of internet networks 

user data base 

printer capability database 

system startup file 

for any local additions 

remote hosts description database 

terminal line configuration data 

terminal line to terminal type mapping data 

for any local entries which may have been added 
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private 

usr/include/* 

usr/lib/aliases 

usr/lib/crontab 

usr/ lib/font/* 

usr/suntool/fixedwidthfonts/* 

usr/Hb/tabset/* 

usr/lib/tmac/* 

usr/lib/uucp/* 

usr/ local 

usr/ preserve 

usr/spool/* 

usr/* 



diskless client private configuration files 

for local subdirectory and any other additions 

mail forwarding data base 

cron daemon data base 

for locally developed font libraries 

for locally developed windows font libraries 

for locally developed tab setting files 

for locally developed tro£f/nro£f macros 

for local UUCP configuration files 

for locally developed programs 

editor temporary files saved here after crashes or hangups. 

for current mail, news, uucp files, etc. 

all users' directories 



You can save your system and user files by running the following commands as "root". Substi- 
tute the correct device abbreviation for your tape controller for tape, and the correct unit 
number for #: 

Table 7-2: UNIX Tape Device Abbreviations 



Abbreviation 



Device 



mt Nine-track magnetic tape 

ar Archive quarter^inch tape 



For example, if you are using your first quarter-inch tape drive, use /dev/rarO. If your system 
doesn't have a tape drive, you'll have to use slightly different commands, also given below, 
which access a tape drive elsewhere on the network. We'll call the machine with the tape drive 
your "remote host". Thus, before you begin, you'll have to know the device abbreviation for 
the remote host's tape drive (abbreviations are the same as in table above), and the remote 
host's hostname. 

1. First, tar off the system files. 
For a machine with a tape drive: 

#cd/ 

# tar cf /dev/r (ape# .??* dev/MAKEDEV.local etc lib usr/include usr/lib 

For a machine without a local tape drive, use the commands below. Substitute your 
remote host's hostname for remote_ho9t. Use 120 for blockjiize on a quarter-inch tape, and 
20 for a half-inch tape. Note that the command should be typed as a single line; it appears 
on two lines because of formatting constraints only: 

#cd/ 

# tar cfb - blockjiizt /dev/rtapei^ .??♦ dev/MAKEDEV.local etc lib usr/include 

usr/lib I rsh remote_ho8t dd of^/dev/ fape# obs=6/ocAL«tzeb 

This makes a tape containing system files which you will need to set up your system after 
the upgrade. 

2. NOW CHANGE TO ANOTHER BLANK TAPE, and run the following command. As 
described just above, substitute the correct device specification for tape^. Also, replace 
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"twcf fl . . ." with the names of all users on your system. (You can double check by looking 
in /etc/passwd or by doing "la usr".) 

For a machine with a tape drive: 

# tar cf dev/r^ape# uBr / {Bpoo\,\oca\,U9 er a fUserbf us erCf us erd...} 

For a machine without a tape drive (note that the command should be typed as a single 
line; it appears on two lines because of formatting constraints only): 

# tar cfb — hlock_sizc /dey/rtapei^ u8r/{8pooI,local,u«era| userbfUsere, userd.,.} | 

rsh rcmote_hodt dd of="/dev/ fapc^ obBsaabhek^sizch 

This makes a tape containing users' files. 

You may want to use other options on the tar commands, such as b to specify a large blocking 
factor such as 126 on Archive quarter-inch tapes, or v to list each file as it is processed. See 
tar (I) for more information. 

Once you have saved the appropriate files in a convenient format, the next step is to dump all 
your file systems to magnetic tape with /etc/ dump (see dump(S)). 

When you have completed your system dump, install the new release from the distribution tape 
as described in the chapter. Installing UNIX for the First Time (except that you may skip the 
disk-reformatting phase); or, if you are installing the release on a machine without a tape drive, 
in the chapter. Installing UNIX on Systems Without Tape Support. Then proceed with the sec- 
tion below. 

7.2. Step 2: Merging 

When your system is booting reliably and you have the root and /usr file systems fully installed, 
you will be ready to proceed to the next step in the conversion process: merging your old files 
into the new system. 

1. Using the first tar tape you created in Step 1, extract the appropriate files into a scratch 
directory, say /usr/ convert. 

For a machine with a tape drive: 

# mkdir /usr/ convert 

# cd /usr/convert 

# tar xf dev/r (ape# 

For a machine without a tape drive: 

# mkdir /usr/convert 

# cd /usr/convert 

# rsh remote_host dd if=/dey/ fape# h8=block_sizeh \ tar xbBf block__size - 

2. Certain files, such as those from the /etc directory, may simply be moved back into place: 

^ cp passwd group fstab ttys ttytype /etc 

# cp crontab /usr/lib 

Remember to remove the old copies after you're sure your system completeness/consistency 
is confirmed. If you wish, you can mv the files instead of copying them. 

Other files must be merged into the distributed versions by hand {dif[l) is often useful 
here). In particular, be careful with / etc/ termcap. 
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3. The spooling and local directories, and the user files saved on the second tar tape may be 
restored in their eventual resting places without too much concern. Be sure to use the p 
option to tar so that files are recreated with the same file modes (you may want to add 
other options, as described in the previous section): 

For a machine with a drive: 

#cd/ 

^ tar xfp dev/rtape=fl' 

For a machine without a drive: 

#cd/ 

# rsh remote_host dd if=/dev/^ape# hB^btockjBizeh \ tar xbBfp hlock_»ize - 

4. Whatever else is left is likely to be site-specific or require careful scrutiny before you place it 
in its eventual resting place. Refer to the documentation (Ater(7), for example) before arbi- 
trarily overwriting a file. 
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Chapter 8 
Hardware Configuration and Expansion 



This chapter describes the seven-slot Multibus card cage in the Model lOOU and the fifteen-slot 
Multibus card cage in the 150U, and gives brief configuration details of the boards which may 
be supplied with them. For specific details of the configuration and descriptions of the boards 
and their jumpers, see the board-level manuals for individual boards. 

In general, the Sun Workstation is shipped with all its boards (tape and disk controllers and 
such) already installed. However, if you are upgrading a Sun to include more peripherals, you 
can use this section to discover how to install the boards and how to set the switches for them. 
This chapter can also be used during troubleshooting, if you need to poke inside the card cage 
and identify the boards. 

8.1. The lOOU Card Gage 

The card cage holding the Model lOOU circuit boards lives in the black cabinet below the moni- 
tor housing. 



Turn off the power and disconnect the power cord before opening up the Sun 
Workstation's enclosure. 



To get to the Model lOOU card cage, first unscrew the six screws on the sides of the black 
cabinet. 

Stand at the back of the Sun Workstation where all the cable connectors are. Gently slide out 
the enclosure. There are many cables and wires connecting the enclosure to various parts of the 
workstation. You must pull the enclosure out gently to avoid breaking anything. Eventually, 
you won't be able to pull it any further because the wires are stretched as far as they can go. 

As you look at the enclosure from the back of the workstation, the power supply is in the metal 
case on the left of the enclosure, and the Multibus card cage is on the right of the enclosure. 
The top of the card cage itself is uppermost, and the top of the boards is to the right. 

The following diagrams show a few typical configurations for the desktop workstation. In the 
diagrams, the notation 'P2' indicates slots spanned by the P2 bus connector. Cards are shown 
in the slots where they are installed at the factory. Detailed explanations of the reasons for 
placing certain cards in specific slots follow this section. 
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Basic Standalone Workstation 
Minimum — with Disk and 1/f* Tape Subsystem 



1 


1/4" Tape Controller 




2 




P2 


3 


Sun-Z CPU 


P2 


4 


1 MByte Main Memory 


P2 


5 


One-board SMD Disk Controller 




6 


7 


Monochrome Display Controller 





Expansion Option for the Standalone Workstation 
1 MByte Additional Memory 



1 


1/4" Tape Controller 




2 


1 MByte Memory Expansion 


P2 


3 


Sun-2 CPU 


P2 


4 


1 MByte Main Memory 


P2 


6 


One-board SMD Disk Controller 




6 


7 


Monochrome Display Controller 





Network Node 
with Local Disk and Tape Storage 



I 


Ethernet Controller 




2 


1 MByte Memory Expansion 


P2 


3 


Sun-2 CPU 


P2 


4 


1 MByte Main Memory 


P2 


5 


One-board SMD Disk Controller 




6 


1/4" Tape Controller 




7 


Monochrome Display Controller 
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Basic Diskless Network Node 



1 


Ethernet Controller 




2 


1 MByte Memory Expansion 


PS 


3 


Sun-2 CPU 


P2 


4 


1 MByte Main Memory 


P2 


5 


6 






7 


Monochrome Display Controller 





Diskless Node with Color Option 



1 


Ethernet Controller 




2 


1 MByte Memory Expansion 


P2 


3 


Sun-2 CPU 


P2 


4 


1 MByte Main Memory 


P2 


5 


6 


Color Display Controller 




7 


Monochrome Display Controller 





Note that the configuration for a minimum standalone workstation (with 1/4^' tape and disk) 
normally takes five slots, leaving two for expansion options. One such option is a second MByte 
of main memory. Note that due to power and operating temperature considerations, a color 
option may not be added to a desktop workstation with local disk storage. Further, since a 
minimum standalone workstation requires 25 amps (and its peak current rating is 35 amps), an 
Ethernet, or a second MByte of memory, or a customer*s own Multibus board may be added to 
such a system but Sun has only tested those configurations shown above. Three principal con- 
straints (slots, power, and cooling) affect the viability of a proposed configuration. 

Also, please note that these diagrams illustrate our current understanding of the best board 
configurations; check with Sun Microsystems or refer to the most recent configuration guides 
released by Sun if you intend to change your card cage layout in any way. 

8.1.1. lOOU Multibus Mastering Schema 

The Model lOOU uses a Multibus backplane employing serial bus arbitration. This places a 
limit on the number of Multibus master cards (cards which use direct memory access — DMA). 
The limit today, as recommended by Intel and verified for our systems by Sun, is three Mul- 
tibus masters. Multibus arbitration logic requires approximately 30 nanoseconds per card; the 
10 MHz arbitration clock imposes the 3 card limit. Of the cards sold by Sun Microsystems, the 
CPU, the SMD disk controllers, and the 1/2-inch (but not the 1/4-inch) tape controller board 
are Multibus master cards. A system with all three of these cards may not operate reliably if 
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you add any additional DMA cards to the system. Note that non-DMA cards, such as Sun 
display controllers, Sun Ethernet controllers, and many other Multibus cards, are not Multibus 
masters and do not come under this restriction. 

In the Multibus mastering scheme, the order of the cards in the card cage determines their 
priority. Slot number 1 is the highest priority bus master, and slot number 7 is the lowest. Bus 
master devices in the lOOU card cage must be in electrically adjacent slots — this means that 
they must either be physically adjacent, or separated by a board which passes the bus arbitra- 
tion signal straight through. Currently, the only Sun boards which are 'transparent' in this 
sense are the 1-MByte Memory board and Rev. C or 'greater' 1/4" Tape Controller boards. 
These boards may therefore be inserted between bus masters. 

8.1.2. lOOU Multibus P2 Connector 

The P2 bus is a high-speed synchronous memory bus that allows memory access without wait 
states. The design of the connector for the P2 bus requires that the processor board and the 
main memory boards be inserted into adjacent slots. The Model lOOU card cage has a P2 con- 
nector across slots 2, 3, and 4. The processor board is usually inserted in slot 3, with main 
memory cards in slots 4 and — possibly — 2. 

Sun Workstation cards use the standard Multibus backplane signals, as defined in IEEE stan- 
dard 790 for the PI bus. Various Sun cards use the P2 bus in different ways, which may not be 
compatible with other vendors' use of this bus. In particular. Sun processor and Sun main 
memory cards do not support extended (24-bit) Multibus addressing on the P2 bus. They use 
the P2 bus for no-wait-state access to main memory. As a general rule. Sun boards and other 
vendors' boards which use the P2 bus should therefore not be installed on the same P2 section. 

The signalling conventions used by the various Sun cards on the P2 bus are documented in the 
hardware reference manual for each board. For further details, please refer to the appropriate 
reference manual. 

8.1.3. lOOU Card Insertion Order 

There are a few restrictions on the placement of cards in the card cage: 

• As stated above, the design of the P2 connector requires that the processor board and 
memory boards be inserted in adjacent slots. 

• With serial arbitration, bus masters (DMA devices) must be in electrically adjacent slots; 
boards which pass the bus arbitration signal through (currently, memory boards and Rev. 
C or greater 1/4" tape controller boards) may be inserted between bus masters. 

• In a desktop workstation which includes a disk controller, the disk controller must be below 
the processor for proper handling of the serial bus priority. If present, the 1/2-inch tape 
controller, a third bus master, must be inserted above the disk controller, because the very 
high throughput of the disk controller might otherwise lock out the lower-priority device 
for excessive periods: 
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Standalone Workstation 
with Disk and 1/2" Tape Subsystem 



1 


2 




P2 


3 


Sun-2 CPU 


P2 


4 


1 MByte Main Memory 


P2 


5 


l/S" Tape Controller 




6 


Xylogicg 450 SMD Disk Controller 




7 


Monochrome Display Controller 





For a customer's own DMA devices, the correct placement order must be determined empir- 
ically. 

• The order in which cards are inserted into the Multibus card cage affects the ability of a 
desktop workstation to maintain proper operating temperatures. Cards that require high 
current also dissipate large amounts of heat and should be placed in slots in the card cage 
that receive the maximum air flow. The top and bottom slots in the card cage receive the 
least amount of cooling. Air flow is greatest across the center three slots in the system. 
The color display controller consumes the most power, and is best placed toward the center 
of the card cage. (In fact, if there are unused slots in the cage, one should be left open 
directly above the color controller board.) 

8.2. The 150U Card Cage 

Open the door of the rackmount system card cage enclosure: the card cage is the vertically 
mounted unit with fifteen slots. The following diagram shows a typical configuration of the 
rack-mountable workstation. In the diagram, the notations 'P2a', T26', and 'P2c' indicate 
slots spanned by a single connector on the P2 bus. Cards are shown in the slots where they are 
installed at the factory. Detailed explanations of the reasons for placing certain cards in specific 
card slots follow this section. 

Please note that this diagram illustrates our current understanding of the best board 
configuration; check with Sun Microsystems or refer to the most recent Configuration Guide 
released by Sun if you intend to change your card cage layout in any way. 
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Model 150U Card Cage 



1 


Sun-2 CPU 


P2a 


2 


1 MByte Main Memory 


P2a 


3 


1 MByte Memory Expansion 


P2a 


4 




P2a 


5 




P2a 


6 




P2a 


7 




P2a 


8 


Ethernet Controller 


P26 


9 


Half-Inch Tape Controller 


P26 


10 




F2b 


11 


Xylogies 450 SMD Disk Controller 


P26 


12 




P26 


13 


Color Display Controller 


P2c 


14 




P2c 


15 


Monochrome Display Controller 


P2c 



Note: the Sun-1 Model 150U card cage iff mounted vertically, with slot 1 at the left. 

8.2.1. 150U Multibus Mastering Scheme 

The Model 150U card cage uses parallel priority bus arbitration. In these systems, there is no 
limitation on the number of bus master cards (DMA devices) which may be inserted in the card 
cage. Of the cards sold by Sun, the CPU, the SMD disk controllers, and the 1/2" tape con- 
troller are masters. The relative priority of each master is determined only by its relative slot 
number; slot 1 is the highest priority. In a parallel card cage, bus master cards need not be 
physically adjacent. 

8.2.2. 150U Multibus P2 Connectors 

The Model 150U card cage has three separate P2 connectors. Slots 1 through 7 share the first 
P2 connector; slots 8 through 12 share the second; and slots 13 through 15 share the third. Sun 
suggests placing the processor card and main memory cards on the first P2 connector, and the 
color graphics controller on the third connector. Disk, tape, Ethernet, and any non-Sun con- 
trollers should be installed on the second P2 connector. 

Sun Workstation cards use the standard Multibus backplane signals, as defined in IEEE stan- 
dard 796 for the PI bus. Sun cards use the P2 bus in different ways, which may not be compa- 
tible with other vendors' use of this bus. For example, the Sun processor and Sun main 
memory cards do not support extended (24-bit) Multibus addressing on the P2 bus. They use 
the P2 bus for no-wait state access to main memory. As a general rule. Sun boards and other 
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vendors* boards which use the P2 bus should therefore be installed in slots with separate P2 
backplane connectors. 

The signalling conventions used by the various Sun cards on the P2 bus are documented in the 
haordware reference manual for each board. For further details, please refer to the appropriate 
reference manual. 

8.2.3. 150U Card Insertion Order 

There are a few restrictions on the placement of cards in the card cage: 

• The design of the connector for the P2 bus requires that the processor board and the main 
memory boards be inserted into adjacent slots. 

• The 3COM Ethernet Board must not share a P2 bus with any other board which uses sig- 
nals from the P2 bus. 

• Because of its high power dissipation, the Xylogics 450 SMD Disk Controller Board should 
be placed in the most central position available in the backplane, as air flow is greatest 
across the center of the card cage. However, the Xylogics board must not share a P2 bus 
with any Sun Microsystems board. For maximum air circulation, leave the slot to the left 
of the Xylogics controller empty if possible. 

• The Sky Floating Point Board must not share a P2 backplane with any Sun Microsystems 
board (it uses the P2 for power and ground). 

• A single Color Display Controller Board must not share a P2 backplane with the Sun-2 
CPU and Memory Boards. If possible, it should be placed toward the middle of the card 
cage to take advantage of the greater air circulation. If there are unused slots in the cage, 
leave one open to the immediate left of the Color Controller Board. 

7) The 1/2-inch Tape Controller Board must not share a P2 backplane with the Sun-2 CPU 
or Memory boards. If present in a configuration which also has a Xylogics SMD disk con- 
troller, the 1/2-inch tape controller should be inserted 'above' the disk controller, because 
the very high throughput of the disk controller might otherwise lock out the lower-priority 
device for excessive periods. 

8.3. Sun-2 CPU 

The Sun-2 CPU (Central Processor Board) of the Sun Workstation is usually close to the top of 
the Multibus card cage — usually in the first slot of the 150U card cage, and the third slot of 
the lOOU card cage. The CPU board has two fifty-pin cable connectors coming off from the top 
of the board. One of the cables splits in two and goes to the connectors labelled "RS232 A" 
and "RS232 B'\ See the subsection. Asynchronous Serial Ports for wiring information. The 
other cable also splits in two and goes to the connectors labelled "Keyboard" and "Mouse". 

The jumpers on the CPU Board should be wired as follows: 

• J700 Bus Priority In (BPRN/) Should be installed in the Model lOOU only. See the subsec- 

tion below, CPU Multibus Priority, for more information. 

• J701 Common Bus Request (CBRQ/) (not installed) See the subsection below, CPU Mul- 

tibus Priority, for more information. 

• J702 Bus Clock (BCLK) (installed) 
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• J703 Constant Clock (CCLK) (installed) 

• J801 Mouse VCC (installed) 

• J400 27128 EPROM's (installed) 

• J401 27256 EPROM's (not installed) 

Only one of J400 and J401 must be installed at a time. 

8.3.1. CPU Multibus Priority 

As shipped, the Sun central processor board (CPU) is always configured as the highest-priority 
Multibus master by placing it in a higher priority slot than all other bus masters in the card 
cage. 

In a Model lOOU, because of its serial card cage, configuring the CPU as the highest-priority 
master also involves installing a jumper at location J700 (along the bottom of the processor 
board) to ground Bus Priority In (BPRN). The processor board can also be run at a lower bus 
priority by removing jumper J700, and thus allowing the processor to receive its BPRN signal 
from the arbitration circuit on the master with higher priority. 

In the Model 150U, the CPU is configured as the highest priority master by simply placing the 
CPU in the highest priority slot in the parallel card cage. 

For both models, if the CPU board is used in conjunction with a Multibus DMA board, such as 
a disk controller, that does not support Common Bus Request (CBRQ), the CPU board must be 
configured such that it gives up the Multibus after every Multibus cycle. This is done by 
jumpering location J701, which is the second jumper from the left along the bottom of the 
board. This also will cause three additional wait states for each Multibus access. The Inter- 
phase 2180 is an example of a Multibus DMA board requiring this configuration. No other 
Sun-supplied boards require this configuration if they are properly configured. See the sub- 
section on each board to determine how to do this. If you have boards from other vendors, 
check this carefully. 

On the other hand, if all Multibus DMA devices (bus masters) do support CBRQ (or if there are 
no Multibus DMA devices), the CBRQ jumper on the processor board is not required. Instead, 
the CPU board will retain bus mastership until a lower priority master requests it by asserting 
CBRQ. Following a CBRQ, the processor board will yield mastership for at least one cycle. For 
certain machine configurations (especially those with color), significant speed enhancements 
result from removing this jumper. 

8. 3.2. Asynchronous Serial Ports 

The Sun Models lOOU and 150U provide two asynchronous serial ports. The ports are controlled 
by the SCC (Serial Communications Controller) on the Sun-2 CPU board. Both ports have 
RS-232-C cabling conventions but use RS-423 signalling. The two serial port connectors are 
labelled "RS-232 A" and "RS-232 B" on the card cage enclosure back panel; these ports 
correspond to /dev/ttya and /dev/ttyb in the system software. 
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Note that older workstations (pre-1.0 Release) have only two serial ports — serial port A is 
configured as a DCE (Data Communications Equipment) and serial port B is configured as a 
DTE. In addition, only serial port A on the older workstations has full modem control. This 
means that external cables built for the Sun-1 or Sun-1.5 CPU either may have to be modified 
to work correctly with the Sun-2 CPU, or a null modem cable may be required. 



The serial ports on the Sun Workstation were designed primarily for connecting output peri- 
pherals — such as terminals, modems, printers, and plotters — and can drive these output lines 
at speeds up to 19.2 Kbaud. All ports provide the CTS, RTS, DTR, DSR, and DCD control 
lines required by some devices (such as modems) in addition to the transmit and receive lines; 
the ports generate DTR and RTS, and pay attention to DSR, CTS, and DCD. All ports are 
wired as DTE (data terminal equipment) ports, and thus permit direct connection of modems 
and the like (25 pins straight through). Computers and other DTE devices can be connected by 
using the null modem cable supplied with your Sun system, or any similar null modem cable. 
The null modem cable provided by Sun has pins 2 and 3 crossed, 4 and 5 crossed, and 6 and 20 
crossed; pins 1 (Frame Ground) and 7 (Signal Ground) are carried through. 

On the CPU Board, I/O channels A and B appear on 50-pin connector Jl. The pin assignments 
for Jl are: 

Table 8-1: Pin Assignments for Jl on the CPU Board 



Jl 


Pin 


Signal 


Pin 


Signal 


3 


TxD A 


28 


TxDB 


4 


DBA 


29 


DBB 


5 


RxD A 


30 


RxDB 


7 


RTS A 


32 


RTSB 


8 


DDA 


33 


DDB 


9 


CTS A 


34 


CTSB 


11 


DSR A 


36 


DSRB 


13 


GND A 


38 


GNDB 


14 


DTR A 


39 


DTRB 


15 


DCD A 


40 


DCDB 


22 


DA A 


47 


DAB 


24 


BSYA 


49 


BSYB 



Connector pins not mentioned are not connected to anything. 

The flat cables that connect to Jl on your CPU board convert this pinout to standard RS-232 
pin assignments. The channels are implemented with three Zilog Z8530 dual UART chips. See 
the Zilog Serial Communications Controller Technical Manual (available from Sun Microsys- 
tems, Part Number: 800-1052-01) for programming information. 

Getting tl»e cabling right is a problem that should be familiar to anyone who has had to connect 
RS-232 equipment; sometimes it is most easily solved by experimenting. A piece of equipment 
known as an EIA Interface Adapter and Monitor — or, colloquially, a 'breakout box' — is 
invaluable in these exercises. Consult a hardware technician or Sun Microsystems if you need 
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help. 

Most devices (other than modems which are answering phones) do not assert carrier properly. 
There is therefore a software facility to simulate asserting carrier: see z»(4S) and oct(4S). 

8.4. Sun-2 Memory Board 

The Sun-2 Memory Board(s) must share the P2 bus with the Sun-2 CPU, and must be physi- 
cally adjacent to the CPU Board due to the design of the P2 connector. They are thus usually 
placed in the second and/or third slots of the Model 150U card cage, and in the second and/ or 
fourth slots of the Model lOOU card cage. In the Model lOOU, Sun-2 Memory Boards may be 
placed between the CPU and other bus masters, as bus priority is passed through the Memory 
Board. This is not an issue for the 150U, as its card cage uses parallel bus arbitration. 

Sun-2 Memory Boards are connected to the Processor Board via the Multibus P2 connector, and 
permit access by the lOMHz MC68010 without wait states. The boards use the Multibus PI 
connector only for + 5 volts and ground connections. 

The first Memory Board provides 1 MByte of main memory for the Sun-2 CPU; each additional 
board provides another MByte of memory. Since the Models lOOU and 150U support up to 2 
MBytes total memory, one board may be added to the basic system. 

To configure a Memory Board, you need only select its starting memory location at or 1 
MByte within the on-board memory address space. Do this by setting the eight-position DIP 
switch located at position U500 on the Memory Board as follows: 

• The first Memory Board should have switch 1 on the DIP switch ON and switches 2 through 
8 OFF. 

• The second Memory Board should have switch 2 on the DIP switch ON and all others OFF. 

8.5. Video Board 

The Sun graphics system is a high-resolution bit-mapped frame buffer and display processor on 
one Multibus board. This board — called the "video board" or "monochrome display con- 
troller" — lives in the bottom slot in the Multibus card cage. The video board has a 10-pin 'D 
shell' connector on the right hand end as you look at the top of the board. 

The video board has one S-section DIP switch, which is used to set the board's Multibus base 
address (in Multibus memory space). It may be set to any address multiple of 0x20000 between 
0x0 and OxEOOOO. The first video board in a Sun system, however, must be set to address 
OxCOOOO; additional video boards are placed at successively lower addresses. 

The following table indicates which switch to set for each of the possible addresses. Note that 
only the indicated switch section should be set to ON; all other sections should be in the OFF 
position. 
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Table 8-2: Video Board Address Selection 



Address 


Section 


0x00000 


8 


0x20000 


7 


0x40000 


6 


0x60000 


5 


0x80000 


4 


OxAOOOO 


3 


OxCOOOO 


2* 


OxEOOOO 


1 



• Setting for First Video Board 

8.6. Xylogics 450 Disk Controller 

The Xylogics 450 SMD disk controller board has five cable connectors on its top: four 26-pin 
connectors and one 60-pin connector. In the Model lOOU card cage, the disk controller board 
must be below the CPU for proper handling of bus arbitration; if there is a 1/2" tape controller 
board in the card cage, it should be plstced in a higher priority position than the disk controller. 
In the Model 150U card cage, the disk controller is placed on the second P2 bus; again, it should 
occupy a lower priority slot than the 1/2" tape controller. 

The Xylogics 450 SMD is an intelligent storage module controller/formatter, using bipolar 
microprocessor technology. It plugs directly into the Multibus and is a bus master during data 
transfers, using a variable burst length DMA technique. It directly connects via industry- 
standard A and B cables to from one to four storage module drives which are available from a 
number of manufacturers. Sun Microsystems supports a family of such drives: the Fujitsu 
M2312K and M2284 Microdisk Drives, and the M2351 Mini-Disk Drive. 

If you need to install the board yourself, the following placement considerations and 
configuration details apply: 

• The Xylogics board shoula not share a P2 connector with the Sun-2 CPU or Memory 
Boards, as it has P2 traces which are incompatible with the CPU/Memory P2 bus. 

• Because the Xylogics board is a Multibus master, its relative slot number determines its 
priority (slot 1 is the highest-priority master). The bosurd must be placed in a lower-priority 
position than the Sun-2 CPU board for proper handling of bus arbitration. It should also 
be placed in a lower-priority position than the 1/2-inch Tape Controller Board, if there is 
one in the system. 

• Since the Xylogics board dissipates a fair amount of heat, it should be placed in the most 
central position possible in the backplane (subject to the considerations listed above). For 
maximum air circulation, leave the slot to the left of the board (as installed) empty if possi- 
ble. 

Several sets of straps are provided for configuring the disk controller board. For proper operar 
tion in the Sun environment, the following options must be selected: 
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• Configure the Xylogics 450 for 16-bit I/O addressing at address Oxee40 by installing 
exactly the following jumpers on jumper group JA through JE: JA3-JB3, JA8-JB8, 
JRl-JCl, JC2-JD2, JC3-JD3, JC4-JD4, and JE4-JE5. 

• Configure the 450 for 20-bit memory addressing. Jumpers are: JM1-JM2 Out; JM3-JM4 
In. 

• Select interrupt level 2: wire pin E2 to pin JX4 (second pin from left in top row of JX 
pins). 

• Enable the BPRO signal: jumper JEl to JE2. 

• Verify that jumpers JH1-JH2 and JN1-JN2 are NOT installed and leave other jumpers 
as shipped from the factory. 

The first controller is configured at address 0xee40 by setting the JA through JE jumper group 
as described above. If you are configuring a second board, it should start at address 0xee48: 
the jumper at JC4-JD4 should be out and one at JR4-JC4 should be in. The system can sup- 
port a maximum of two Xylogics 450 controller boards. 

Please note that if you have an Interphase 2180 disk controller board in your system, only one 
Xylogics board can be supported. The Xylogics board should be configured for address ee40; the 
Interphase should be configured for address 48 as described below. 

For the full specification and detailed description of the disk controller, see the supplied docu- 
ment: XylogicB Model 4^0 Peripheral Processor SMD Disk Subsystems Mainteriartce and Refer- 
ence Manual. 

8.7. Interphase 2180 Disk Controller 

The Interphase Disk Controller Board has five cable connectors on its top: four 26-pin connec- 
tors and one 60-pin connector. In the Model lOOU card cage, the Interphase board must be 
below the CPU for proper handling of bus arbitration; if there is a 1/2" tape controller board in 
the card cage, it is placed above the disk controller. In the Model 150U card cage, the Inter- 
phase disk controller is placed on the second P2 bus; again, it should occupy a lower priority 
slot than the 1/2" tape controller. 



Note that the Interphase controller does not generate CBRQ/; the CPU board must be 
configured to take this into account. On the CPU board, the jumper at location J701 must be 
installed. See the section, CPU Multibus Priority for more information. 



The Interphase SMD 2180 is an intelligent storage module controller/ formatter, using bipolar 
microprocessor technology. It plugs directly into the Multibus and is a Bus Master during data 
transfers, using a variable burst length DMA technique. It directly connects via industry stan- 
dard A and B cables to from one to four storage module drives which are available from a 
number of manufacturers. Sun Microsystems supports two such drives: the Fujitsu M2312K 
('D84') and M2284 ('D169') Microdisk Drives. Note that the Interphase 2180 is not suitable for 
use with the Fujitsu M2351 ('D474') Mini-Disk Drive, also supported by Sun. 

Four sets of straps and two 8-bit DIP switches are provided for configuring the Interphase disk 
controller board. For the UNIX system on the Sun, the following options must be selected: 

• Install the M3 jumper, selecting "increment by head" rather than "increment by cylinder". 

• Switch #3 on DIP switch S2 must be ON, selecting level 2 interrupts. 
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On DIP switch SI, set switch #8 ON, set #7 OFF, selecting 512 byte sectors, 34 sectors 
per track. 

Switches #1-6 on DIP switch SI determine the address of the controller in Multibus I/O 
space. They supply the bits; 654321xx of the 8-bit Multibus I/O address. The board can be 
written to at four consecutive addresses, and read from at the lowest of the four. The Sun 
Workstation only uses addresses 0x40, 0x44, 0x48, or 0x4C. These addresses are obtained 
by setting the switches on DIP switch SI as follows: 

Table 8-3: Selecting Disk Controller Base Address 



Desired 
Address 


Switch 
6 


Switch 
5 


Switch Settings 

Switch Switch 

4 3 


Switch 
2 


Switch 

1 


0x40 


Off 


On 


Off 


Off 


Off 


Off 


0x44 


Off 


On 


Off 


Off 


Off 


On 


0x48 


Off 


On 


Off 


Off 


On 


Off 


0x4C 


Off 


On 


Off 


Off 


On 


On 



Normally, the first Interphase controller in the system is configured at address 0x40 by set- 
ting switch #5 on DIP switch SI ON and all others OFF . If you also have a Xylogics 
board in your system, configure the Interphase instead for address 0x48 by setting switch 
#2 ON and all others OFF. 

• Finally, the Interphase controller board is normally configured to have lower Multibus 
priority than the CPU board by installing jumper E to F. 

Sun recommends a maximum of one Interpnase disk controller board per system. 

For the full specification and detailed description of the disk controller, see the supplied docu- 
ment: SMD 2180 Storage Module Controller I Formatter User 's Guide. 

8.8. Nine- Track Tape Controller 

If your Sun system is shipped with a nine-track tape unit, there should be a tape controller for 
that subsystem installed in the card cage. The tape controller is a TAPEMASTER board from 
Computer Products Corporation, The TAPEMASTER nine-track tape controller board has two 
50-pin cable connectors on its outside edge (viewed installed in the czid cage). 

As shipped, the TAPEMASTER should be configured correctly for your Model lOOU or 150U. 
If you are installing the board, please verify the following: 

• For a lOOU, locations 1 to 2 are jumpered; they must be jumpered for serial backplanes. 

• For a 150U, locations 1 to 2 are not jumpered; they should be jumpered for serial back- 
planes only. 

• For both models, locations 3 to 4 and locations 52 to 53 must be jumpered for proper han- 
dling of CBRQ/: if these locations are jumpered, the tape controller will surrender the bus 
to a higher-priority master when that master activates CBRQ/. If you configure the board 
in any other fashion, you must also configure your Sun-2 CPU so that it gives up the Mul- 
tibus after every cycle by installing the jumper at location J701 on the CPU board. 
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There are also board placement considerations involved in installation: 

• The TAPEMASTER board should not be placed on the same P2 connector as the Sun-2 
CPU and Memory Boards. 

• The nine-track tape controller is a Multibus master. This means that the relative number 
of its slot determines its priority (slot 1 is the highest-priority master). The board must be 
placed in a lower-priority position than the CPU. If you have a Xylogics 450 SMD Con- 
troller Board in your system as well, place the TAPEMASTER Board in a higher-priority 
position; otherwise, the Xylogics board will lock out the TAPEMASTER (due to its higher 
data transfer rate). 

To cable up the tape controller, connect the 50-pin ribbon cable coming from the backpanel 
connector labelled "DISK/TAPE COMMAND B" to the "J2" connector in the center of the 
TAPEMASTER board. The 50-pin ribbon cable from the back panel connector labelled 
"TAPE COMMAND A" should go to the "Jl" edge connector of the TAPEMASTER board. 

As shipped, the tape controller board should already be set up to work correctly in a Sun sys- 
tem. Refer to the Computer Products Corporation TAPEMASTER Manual for details of 
configuring the board if required. 

8.9. Quarter- Inch Tape Controller 

The Sun tape interface board consists of an interface to an Archive 1/4'' streaming tape unit 
and 256 KBytes of Multibus memory with parity. The tape controller is not a bus master, and 
boards which are Rev. C or 'greater' may actually be placed in a slot between bus masters (in 
the Model lOOU), as they pass bus priority through. 



Note that you must disable the Multibus memory on the Tape Controller Board if you have a 
Sun-2 CPU in your system. To do this, open all switches on switch package U50, as described 
below. 



There are four 8-position DIP switches on the tape controller board. They are used to select the 
interrupt level at which the tape controller will interrupt the processor, select the base address 
for the Multibus memory on the board, and to select the base address for the Multibus I/O 
registers which communicate commands and status information between the tape controller and 
the central processor. 

With the Multibus connectors facing you, the switches are all in the lower left hand corner of 
the board, at component locations U52, U50, U53, and U56. U52 is in the lower left-hand 
corner of the board; U50 is directly above U52; U53 is to the immediate right of U50; and U5d is 
to the immediate right of U53. For each package, switch #1 is on the right and switch #8 is 
on the left. 

Switch package U52 selects the interrupt level; switch ^1 selects interrupt level 0, switch #8 
selects interrupt level 7. The desired switch should be closed (or ON); all others should be left 
open (or OFF). The table below shows the switch settings. The Sun system is configured to 
run with level 3 interrupts from the quarter-inch tape controller. 
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Table 8-4: Selecting Quarter-Inch Tape Controller Interrupt Level 



Required 

Interrupt 

Level 


Close 

Switch 

Number 


Required 

Interrupt 

Level 


Close 

Switch 

Number 





1 


4 


5 


1 


2 


5 


6 


2 


3 


6 


7 


3 


4 * 


7 


8 



* Note that this is the standard setting. 

Switch package U50 selects the base address for the Multibus memory. This memory must be 
disabled for proper operation with the Sun-2 CPU: all switches on U50 should be opened. If 
you are not using the tape controller board with a Sun-2 CPU, and need to make use of the 
Multibus memory, see the next subsection for switch settings. 

Switch packages U53 and U56 select the base address of the I/O registers that the tape con- 
troller uses in Multibus I/O address space. The tape controller uses eight consecutive bytes of 
Multibus I/O space, and this block of eight registers must be located on an eight-byte boun- 
dary. DIP switch packages U53 and U56 decode address lines A15 through A3. Switch #8 on 
U53 corresponds to A15; switch #1 on U53 corresponds to A8; switch #8 on U56 corresponds to 
A7; and switch ^^4 on U56 corresponds to A3. Address lines AO through A2 are not decoded 
through the switches. 

Switch #1 on U56 enables/disables the tape section on the board. 

Switches ^^2 and ^^3 on U56 are not used and their settings are irrelevant. 

The table below illustrates the switch settings in a diagrammatic form. A corresponds to an 
open (or OFF) switch, while a 1 corresponds to a closed (or ON) switch. 

Table 8-5: Selecting Quarter-Inch Tape Controller Base Address 



Required 
Address 


Switch Settings 
U53 U56 


OxFOOO 


11110000 


00000000 


0x1238 


00010010 


00111000 


0x200 ♦ 


00000010 


00000000 


Disable 
Tape 


xxxxxxxx 


xxxxxxxl 



* Note that this is the standard setting. 
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8.9.1. Tape Controller Multibus Memory 

This subsection is irrelevant to you if you are using your 1/4" tape controller board with a 
Sun-2 CPU; the tape controller Multibus memory is unnecessary with such a configuration, and 
must be disabled as described above. 

If you need to make use of the 256 KBytes of Multibus memory on the tape controller board, 
select the base address for the memory as follows. 

Memory on the tape controller board comes in 128K byte chunks; there are two of these chunks. 
The chunk(s) of memory may be located on a 128K byte boundary anywhere within a one 
Megabyte address space by closing appropriate switches on package U50. 

With the Multibus connectors facing you, the four switch packages are in the lower left hand 
corner of the board, at component locations U52, U50, U53, and U56. U52 is in the lower left- 
hand corner of the board; U50 is directly above U52. For each package, switch #1 is on the 
right and switch #8 is on the left. 

Two adjacent switches on U50 should be closed. This places the 256K bytes of memory on the 
0, 128K, 256K, 384K, 512K, 640K, or 7e8K boundaries. All other switches on package U50 
should be opened. 

If all switches on U50 are opened, all memory accesses to the tape controller board are disabled. 
The table below illustrates the switch settings in detail. 

Table 8-6: Selecting Quarter-Inch Tape Controller Memory Base Address 



For 256K Byte Tape 


Controller Boards 


Closing 


Selects Address Range 


Switch 
Numbers 


Decimal 


Hexadecimal 


8 and 7 


— 256K-1 


0x0 — 0x3FFFF 


7 and 6 


128K — 384K-1 


0x20000 — Ox5FFFF 


6 and 5 


256K — 512K-1 


0x40000 — 0x7FFFF 


5 and 4 


384K — 640K-1 


0x60000 — 0x9FFFF 


4 and 3 


51 2K — 768K-1 


0x80000 — OxBFFFF 


3 and 2 


640K — 896K-1 


OxAOOOO — OxDFFFF 


2 and 1 


768K — lM-1 


OxCOOOO — OxFFFFF 



8.10. 3COM Ethernet Controller Board 

A Sun-1 Workstation in a networked environment is currently supplied with a 3COM 3C400 
Ethernet Controller Board. The 3COM Ethernet controller is a memory-mapped device in the 
Sun Workstation. There are several jumpers that should already be set correctly when the Con- 
troller leaves the factory. Correct settings of the jumpers and switches for the Sun environment 
are as follows: 
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• The Ethernet controller should be set for 20-bit memory addressing. Look at the board 
with the components up and the Multibus edge connectors facing you. At the lower left 
corner of the board there are two jumpers labelled JPl and JP2. There should be a short- 
ing jumper on JP2) there should not be any shorting jumper on JPL 

• Just to the right of the address width selection jumpers, there is a row of jumper pins. The 
pins marked MRDC and MWTC should have shorting jumpers installed. The pins marked 
lORC and lOWC should not have any jumpers installed. 

• Then there is a row of jumpers marked INT7 at one end,^ down to INTO at the other end; 
these select the interrupt level. For the Sun Workstation, select interrupt level 3 — install 
a shorting jumper on the fourth pair of jumper pins from the right-hand end of the row. 
Remove the jumpers from all other INT(n) pins. 

• The switch marked ADR17/ at the bottom right-hand corner of the board should have all 
its kcyswitches set to OFF. 

• The switch marked ADRlSf in the lower left-hand corner of the board selects the memory 
base address for the board. The Ethernet controller board consumes 8K bytes of Multibus 
memory space. 

• The Sun Workstation expects to find the first Ethernet board's memory at address 
OxEOOOO. This address is selected by setting keyswitches 1, 2, and 3 on the switch 
marked ADR 13/ to ON and the other switches to OFF. 

• The Sun Workstation expects to find the second Ethernet board's memory at address 
Oxe2000. This address is selected by setting keyswitches 1, 2, 3, and 7 on the switch 
marked ADRIS/ to ON and the other switches to OFF. 

• In all cases, keyswitch 8 on the switch marked ADRIS/ should always be OFF. 

• In component position 12 on the Ethernet controller board there is a PROM which contains 
the hardware Ethernet address for this board. 

8.11. Sky Floating Point Board 

In both the Model lOOU and the Model 150U card cages, the Sky floating point processor may 
be placed in any available slot which does not share a P2 bus section with any Sun board which 
uses the P2 bus. The Sky board does IEEE format floating-point calculations much faster than 
they can be done in software, and so makes many compute-intensive programs run significantly 
faster. 

To run in the Sun environment, the Sky board must be set to interrupt on level 2, and 
configured for Multibus I/O address 0x2000. If you purchased your board from Sky, you must 
set these parameters by rewiring pins at jumper block locations JP02 and JPOl, as follows: 

• Holding the board with the Multibus edge connectors facing down (the location numbers on 
the board will be right side up)> locate JP02 and JPOl: they are the two blocks with 
exposed pins near the lower left-hand corner of the board. JP02 is the leftmost block. In 
the following diagrams, we assume that the board is in this position. 
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• To set the interrupt level to 2, replace the wire between pins 2 and 6 of JP02 by two wires: 
one between pins 1 and 6, and one between pins 3 and 6 (leave the shunt between pins 4 
and 5 on): 

Table 8-7: Selecting SKY Board Interrupt Level 



14 


13 


12 


11 


10 





8 




14 


13 


12 


11 


10 





8 


• 
• 


• 


• 


• 


• 


• 


• 
• 




• 


• 


• 


• 


• 


• 


• 
• 


4 


• 




— • 


^ 


6" 


• 


« 


•— 


— • 


s 



1234567 1234567 

Before After 

• To set the address of the board to 2000 in Multibus I/O space, replace the shunt 
between pins 1 and 2 of JPOl with a wire between pins 1 and 11 of the same jumper 
block: 

Table 8-8: Selecting SKY Board Base Address 



14 13 12 11 10 8 




14 13 12 11 10 8 






• ••#••• 



1234567 1234 5 67 

Before After 

For more information, see the Installation Note* for SKY FFP document shipped with the 
board. 
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Appendix A 
Power-up and Bootstrap 



The central processor board (CPU) of the Sun Workstation has a set of ROMs which con- 
tain a program generally known as the "monitor". The monitor controls the operation of 
the system before the UNIX kernel takes control. 

The first, second, and third major sections in this appendix cover the startup and bootstrap 
functions of the monitor. Under normal circumstances, the monitor automatically 
bootstraps the UNIX system after initial power-on; no manual intervention is required. 
These sections describe how it does that, and how to "boot" manually when necessary. 

The fourth section lists messages which the monitor and boot program can display. These 
should be useful for troubleshooting. 

For information on the PROM Monitor commands, see the CPU PROM Monitor document 
in the Sun System Internals Manual. 

A.l. Power-On Self Test Procedures 

When system power is first turned on, the monitor runs a quick self-test procedure. The 
test can have one of these results: 

• Critical errors are found. The screen remains dark. The error is reported on eight 
LEDs on the CPU board in the card cage. 

• No video board is found. The monitor sends its output to serial port 'A' (labelled 
"RS-232 A" on Model 100U/150U backpanels, and "SIO-A" on Model 120/170 
backpanels). Connect an ASCII terminal to this RS-232 connector. Configure the 
terminal for 9600 baud, no parity, one stop bit. Then power on the workstation 
again and look for messages on the terminal. 

• Non-critical errors are found These are reported to the screen, and the system 
begins the automatic boot process. 

• No errors are found. This is reported to the screen, and the system begins the 
automatic boot process. 

A.1.1. Critical Errors from Self Test 

Severe problems are reported using the eight miniature LEDs on the CPU board. Depend- 
ing on your workstation model, you get at these differently: 
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• With a Sun-1/lOOU, these LEDs can be glimpsed through the cooling slots on the left 
side of the monitor base. If your screen remains dark, and you see more than one LED 
on in the middle of some board in the card cage, youMl probably have to slide the 
drawer out of your Sun-1/lOOU to really see the error code in the LEDs. 

• With a Sun-l/150U or Sun-2/170, you can see the LEDs by opening the front door of 
the card cage enclosure. 

• With a Sun-2/120, pull ofif the front plastic panel of the pedestal; the row of 8 LEDs is 
on the front edge of a card in the middle of the card cage. 

When power is first applied to the workstation, all eight LEDs light, then each lights 
quickly in sequence. Following this 'lamp test^ the lights blink rapidly as each test is 
passed. The lights slow down as memory is tested; each of the two memory tests takes a 
few seconds per megabyte. Finally, three LEDs on the end light momentarily, then all the 
LEDs go off except for a middle LED which blinks about once a second. If your worksta- 
tion follows this sequence, self-test has not found a critical problem. (Once UNIX or other 
programs have gained control of the system, they can use the LEDs in other ways. This 
description only applies to the power-on sequence.) 

If at some point in the above sequence, the lights freeze (keep the same pattern for more 
than a minute), or the sequence restarts from the beginning, there is a critical hardware 
problem with the workstation. The appropriate thing to do in this case is to contact Sun 
Microsystems Field Service or your local Field Service organization. Copy down the pat- 
tern of lights (as well as you can, if it is repeating over and over); they contain important 
diagnostic information for Field Service. 

A.1.2. Non-Critical Errors from Self Test 

Non-critical errors result in a display like the following: 

Self Test found a problem in something 

Wrote wdata at address addr, but read rdata. 
Damage found, damages 

~> Give the above information to your service-person 

Sun Workstation, Model modeijnumber , type^ofjseyboard. 
RQM Rev N, *omc_n«m6cf_A/B memory installed 
Serial H^tomejntimber, Ethernet address n:n:n:n:n:n 

Auto-boot in progress . . . 

something shows what part of the system was most recently found to be malfunctioning. 
(If more than one error occurs, a summary of all errors is given in the damages 
section, and details about the last error are reported here.) 

wdata is the data that was written into part of the system, or which was expected to 

be there if the system was functioning normally. 

addr is the address where the data was read and/or written. For memory errors, 

this is a physical memory address; for other errors, the interpretation of the 
address depends on something, 

rdata is the data that was read back from addr and was found to be invalid because 

it was not the same as wdata. 
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damages is a list of all subsystems which were found to have errors. There is not 

enough room to save information about all of the errors that were found (only 
the last one), but this minimal information about each is recorded. 

You should copy down the information from the screen, then call Sun Microsystems Field 
Service, or your local Field Service representative. The system will attempt to bootstrap 
itself despite the error. 

A.1.3. No Errors from Self Test 

The following display results: 

Self Test completed successfully. 

Sun Workstation, Model model_number , type_ofJityboard. 
ROM Rev N, some_number_MB memory installed 
Serial #«omc_n«m6cr, Ethernet address n:n:n:n:n:n 

Auto-boot in progress . . . 
The monitor then begins auto-boot. 

A.2. Automatic Boot Procedure 

The monitor immediately attempts to boot from a default device (it tries a Xylogics SMD 
Disk Controller, then a SCSI Disk Controller, and finally tries to boot over the network): 

Auto-boot in progress 

Boot: rfi«Aj(0,0,0)vmunix 

Load: (/t«A;(0,0,0)boot 

Boot: rfi«/:(0,0,0)vmunix 

Size: 215040-1- 24576+ 30916 bytes 

Sun UNIX 4.2, etc... 

Disk is the device name of the "best" local or network disk the monitor could find. The file 
called vrminix is booted from it. This file does not have to contain a UNIX kernel; it can con- 
tain any program you like, as long as the disk is in 4.2BSD UNIX file system format. It is 
also possible to set up the disk to boot a small program which need not be in a UNIX file 
system. This discussion assumes that the disk is set up for UNDC 

A.3. Booting from Specific Devices 

The Sun Workstation can be booted from: 

• Any logical partition of a local disk. 

• Any publicly available network disk partition on your Ethernet. 

• The first file of a local tape drive. 

As mentioned above, the monitor automatically attempts to boot vmunix from a default 
disk. If you want to boot a different program, or from a different device, you must stop the 
automatic boot process by aborting. The specific abort sequence depends on your keyboard 
type. For a Sun-1 Model lOOU or 150U, the sequence is either 'SET-UP-A' (hold down the 
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'SET-UP' key while typing the 'A' key) or 'ERASE-EOF-A'. For a Sun-2 keyboard, the 
abort sequence is 'Ll-A'. For a standard terminal, the BREAK key generates an abort. 
When you abort, the monitor displays the address where it aborted and a ">" prompt, 
and waits for you to type a command. 

The monitor's boot command looks like: 

> b device(parameters)pathname args 

where device is the type of hardware to boot from, parameters specify the address or parti- 
tioning of the device, pathname is the name of the actual file (in a UNIX file system on that 
device) to boot into memory, and arg» are optional arguments to the program. 

To determine which devices your monitor ROMs are able to boot from, you can use the 
command: 

> b? 

The devices are shown in order from "best" to "worst", as used by the automatic boot pro- 
cedure to select a boot device. 

Booting a program involves the cooperation of up to three different programs within your 
Sun Workstation. The first is the monitor, which reads in the "boot program" or "mini 
boot program", depending on the device. If the "mini boot" is used, it in turn reads in the 
"real" boot program. Once the "real" boot program is running, it finds and reads in the 
program you wanted to run. This process is more or less obvious depending what device 
you are booting from. Where there are minor differences between the commands you enter 
to the monitor and to the boot program, these will be noted. In general, the difference is 
that the monitor commands start with 'b' and the boot program's commands don't. 

A.3.1. Booting from Disk 

For disk drives, the format of the boot command is: 

> b controUer(addre99,drive,partit%on)pathname args 

controller names the disk controller which runs the specific disk: ip for the Interphase 
2180 disk controller, xy for the Xy logics 440 or 450 controller, or sd for a 
SCSI disk controller. 

address can either be a small number, indicating the nth standard controller board, or 

is the physical address of the controller on the Multibus. 

drive is the unit number of the disk on that specific controller. 

partition is a number corresponding to the logical partition on the disk where the file 
specified by pathname can be found. Zero corresponds to partition 'a', 1 to 
'b', etc. 

pathname is the name of the file to boot. 

args are optional arguments. 

A.3.2. Booting from Network Disk 

To boot the system from network disk, use a command like: 
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> b controller{address, hostnumher, partition)pathname args 

controller is the device abbreviation for your Ethernet Controller: ec for a 3COM Ether- 
net Controller, or ie for a Sun-2 Ethernet Controller. 

address can either be a small number, indicating the nth standard controller board, or 

is the physical address of the controller on the Multibus. 

hostr^umber is an arbitrary number (between 1 and 255) assigned to each machine on a 
local network to uniquely identify the machine. To find the host number of 
an existing node, check the node's /etc/ hosts file. The entries in the file look 
something like: 

102.0.1.1 winkin 

102.0.1.2 blinkin 

102.0.1.3 nod 

102.0.1.24 henry 

The last component of the complete internet address is the host number. 
Henry's host number here is 24. Note that you must supply the host number 
to the monitor in hexadecimal; the numbers in /etc/hosts may be in decimal, 
so you may have to convert. 

Using zero as hostriumber is valid here, and means 'whichever host is my net 
disk server,' 

partition is the desired public partition number on the specified server. The correspon- 
dence between this number and a real disk partition is defined in / etc/ nd. local 
on the server machine. 

pathname is the name of the file to boot. 

args are optional arguments. 



A.3.3. Booting from Tape 

The Sun Workstation can be booted from industry-standard nine-track magnetic tape, from 
a 1/4-inch cartridge tape controlled by a Sun 1/4-inch tape controller, or from a 1/4-inch 
tape controlled by a SCSI tape controller, using the following command: 



> b tape {controller, unit, filenum) 



tape 



is the device abbreviation for your tape controller: ap for a Sun 1/4-inch tape 
controller, mt for nine-track tape, or st for a SCSI tape controller. 

controller is a small number indicating the nth standard magnetic tape controller in the 
system, or is the Multibus address of the controller. 

unit specifies which tape drive on the controller is to be used. 

filenum specifies which file of the tape is to be booted. By convention, boot com- 

mands number the first file on the tape file ^0, the second #1, and so on. 

The monitor ignores the supplied value of filenum and can only boot the first file on a tape. 
To boot a file further down the tape, use the monitor to boot the "boot" program. Sun- 
supplied UNIX distribution tapes always have the "boot" program on the first file of the 
tape. 
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A.3.4. Booting Files from the Default Device 

To boot any file from the default device, enter: 

> b pathname args 

This is useful for booting standalone utility programs, once your disk or network disk is set 
up, or for trying new versions of the UNK kernel. 

A.4. Messages from the Monitor and Boot Program 

Abort at aaaaaa 

The monitor has aborted execution of the current program because you entered the 
"abort sequence" (upper left key held while pressing "A") from the Sun keyboard, or 
pressed BREAK on a serial console, aaaaaa is the address of the next instruction. You 
can continue the program from there by entering the "c" command. 

Address Error, addr: Z2zzzz at aaaaaa 

The current program has stopped because it made an invalid memory access, xxxzxx is 
the (invalid) address; aaaaaa is an address near the instruction which failed (typically 
two to ten bytes beyond). There is no general way to recover from this error, except to 
debug the program. 

ar: cartridge is write protected 

The current program is trying to write on an Archive tape cartridge, but the "Safe" 
switch at the top left corner of the cartridge is set to prevent writing on the tape. 

ar: xxxx error 

The monitor or boot program is trying to boot from an Archive tape, and encountered 
an unexpected error. The status bjrtes xxxx can be decoded by looking under "Read 
Status Command" in the Archive Product Manual. This error could be caused by 
incorrect cables, a bad tape, or other problems. 

ar: drive not responding 

The monitor is trying to boot from an Archive tape, but can get no response from the 
tape drive. This can occur if your system contains an Archive controller board but no 
tape drive, or if the tape drive's cable is loose or disconnected, or if the tape drive's 
power is not on. 

ar: invalid state xx 

This message indicates that the standalone I/O system has a bug in its Archive driver. 

ar: no C2u*tridge 

ar: no cartridge in drive 

The monitor or boot program is trying to boot from an Archive tape, but there is no 

cartridge in the tape drive. 

ar: no drive 

The monitor or boot program is trying to boot from an Archive tape, but the specified 
drive does not exist. Typical Archive configurations include only drive 0. 

ar: RDST gave Exception, retrying 

The current program is trying to use the Archive tape drive, and encountered an error. 
The error is probably caused by hardware. Check the cable(s) that connect the tape 
drive to the system. 
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ar: triggerred at idle zz 

This message indicates that the standalone I/O system has a bug in its Archive driver. 

Auto-boot in progress... 

The monitor has finished its power-on sequence and is looking for a good device to boot 
the Unix system from. 

Bad device 

The current program (possibly the boot program) has tried to open a file without a 
device name (eg zy()). This could mean that the boot command you typed had no dev- 
ice name. 

Bad format 

The boot program is trying to boot from a file which is not in a standard UNIX a.out{b) 
format. The boot program can only boot files which are in this format, which is gen- 
erated by the ld(l) command. 

bn negative 

bn ovf dd 

bn void dd 

A standalone program (such as the boot program) is trying to read a file from disk or 
net disk, and the block number it is trying to read is invalid. 

Boot: 

The boot program is waiting for you to specify a device and file name to boot from. 
The boot program accepts the same commands that the monitor would, without the 
initial 'b'. See the section Booting From Specific Devices above. 

Boot: dev(ctlr,unit,part)name options 

The monitor or boot program is preparing to boot the specified file from the specified 
device. Either you typed a boot command, or this is an auto-boot after power-on. dev 
is the device type; cilr, unit, and part are the controller, unit-within-controller, and disk 
partition number. Name is the name of the file to boot from, if any; options are argu- 
ments for the booted program, such as '-9\ If you enter a boot command to the moni- 
tor, this message will be printed twice; once by the monitor and once by the boot pro- 
gram. 

boot failed 

The boot program has tried to boot the device and/or file you specified, but could not. 
A preceding message should give more details about why. 

Boot syntax: b [!][dev(ctlr,unit,part)] name [options] 

boot syntax: dev(ctlr,umt,part)name 

You have entered an invalid boot command. This message describes the general format 
of the boot command to remind you. The first form is used by the monitor; the second 
(without the 'b') is used by the boot program. Don't type the brackets; they indicate 
optional parts of the command. 

Bus Error, addr: zxzzzz at aaaaaa 

The current program has stopped because it tried to make an invalid memory access. 
The reason for the error is shown before this message. The memory location being 
accessed was zzzzzz, and the instruction which made the access is near location aaaaaa. 
There is no way to recover from this error, in general, except to debug the program. 

Can't write files yet... Sorry 

The current program is trying to write to a disk or network disk file thru the stan- 
dalone I/O system. Writing on files (as opposed to writing on devices) is not supported 
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when running standalone (i.e. before booting the Unix kernel). 

Corrupt label 

Corrupt label on head h 

The monitor or boot program is trying to boot from a disk. The first sector of the disk 
appears to be a label (as it ought to be), but the checksum on the label is wrong. Try 
again a few times; if the problem recurs, you should probably relabel your disk. See 
sections '^Using the Diag Utility'^ and "Labelling the Disk'' in the chapter, InttaUing 
UNIX for the First Time. Before trying to relabel your disk, make sure that you know 
what ought to be in the label — writing the wrong label on the disk is highly likely to 
cause destruction of some or all files on the disk. 

connt^ dddt 

A standalone program is trying to write to a device and has specified a block size which 
is not a multiple of 512. The write proceeds anyway, but may cause incorrect results. 

Damage found, damage... 

As part of the power-on self test procedure, the monitor has found damage in one or 
more parts of the system. This message should be reported to your local service 
representative or Sun Microsystems Field Service. Damage is a list of subsystem 
names, such as "memory" or "timer". 

Exception ee at aaaaaa 

The current program has stopped because it got an interrupt. The interrupt could 
have been caused either by hardware or software, ee is the hexadecimal address of the 
interrupt vector used; you can look it up on a Motorola 68010 or 68000 reference card 
or CPU manual to see what kind of interrupt has occurred, aaaaaa is the address of 
the instruction where the interrupt occurred. 

Extra chars in command 

Your previous *u' command had extra, unrecognized characters on the end. 

FCn space 

fhe address space being accessed by the monitor's memory reference commands is 
defined by Function Code number n. See the Motorola 68010 CPU manual for more 
information. This message is printed by the *s' command. 

For phys part p. No label found. 

The boot program is trying to boot from a nonzero "physical partition" on a disk, and 
can't find a label. Physical parititions are used for disk drives part of which are fixed 
and part of which are removable. 

— > Give the above information to your service-person. 

The monitor has found a hardware problem while executing its power-on self test pro- 
cedure. The preceding messages describe the error in more detail. You should report 
the problem to your local service staJQf, or to Sun Microsystems Field Service. 

Giving up.. 

See "Waiting for disk to spin up...". The monitor has given up on waiting for the disk 
to become ready. 

ie: cannot initialize 

The monitor or boot program is trying to boot from a Sun-2 Ethernet controller, and 
something serious has gone wrong with the board. Call your local Sun Microsystems 
Field Serviceperson. 

ip: error zx 

The monitor or boot program is trying to boot from an Interphase disk controller, and 
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encountered an unexpected error. The error number zz can be decoded by looking in 
appendix B of the Interphase SMD 2180 Storage Module Controller J Formatter User's 
Guide. This problem is usually caused by loose or unplugged disk drive cables. 

ID PROM INVALID 

The monitor cannot find a valid ID PROM on the CPU board. The ID PROM con- 
tains the machine's serial number and other information specific to your system. If you 
have recently changed CPU boards, it is possible that you installed the ID PROM 
incorrectly. You should attempt to locate the correct ID PROM and install it in your 
CPU board. 

Invalid Page Bus Error ... 

See "Bus Error...", The attempted access was invalid because the virtual page contain- 
ing the addressed data has been designated as invalid. It usually means that your pro- 
gram is using the wrong address. 

Invalid selection 

Your last 'u' command was not correct. 

Keyboard error detected 

The microprocessor on the keyboard has reported an error. This probably means that 
your keyboard hardware is broken and should be replaced. 

Load: dei{ctlr,unit,part)hooX 

The monitor has loaded in the ''mini" boot program from a disk drive or network disk. 
The mini boot is now reading in the "real" boot program from the disk. The "real" 
boot program will then read in the program you requested. 

Lower Byte Parity Bus Error .. 

Sec "Bus Error. /' and "Parity...". The preceding access was to a word in memory 
with a parity error in its lower byte. 

Misplaced label on head n 

The monitor or boot program is trying to boot from a disk. It has found a label which 
accms to identify itself as belonging to a di£ferent read/write head from the one where 
the label is written. See "Corrupt label" above. 

mt: controller does not initialize 

The monitor is trying to boot from nine-track tape, and could not get the tape con- 
troller to complete its initialization sequence. This might indicate a possible defect in 
the controller, or incorrect configuration of the controller board. 

mt: error Q^zz 

The monitor is trying to boot from niue-track tape, and encountered an unexpected 
error. The error number zz can be decoded by looking in appendix C of the Tapemas- 
ter Product Specification, which is supplied with your tape drive. 

mt: unit not ready 

The monitor is trying to boot from nine-track tape, but the tape drive is not ready. 
Check to see that the drive is on-line. 

nd: no file server, giving up. 

The monitor or boot program is trying to boot from a network disk server over the 
Ethernet. It has been retrying for a long time and there is no response from the server. 
Check the Ethernet address in the boot command; if it is zero, make sure your 
machine's Ethernet address is recorded in the server's /etc/nd,local file. If that's OK, 
check your Ethernet cable connection, see whether the server is running correctly, 
and/or see whether other machines on the network can communicate. 
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No controller at mbio xxxx 

The monitor is trying to boot, but it can't find a device controller where you asked it 
to look. You should try another boot command, or make sure that your controller 
board is plugged in and has all its jumpers and switches set properly. 

No default boot devices 

The monitor is trying to boot but it can't find a disk or Ethernet interface to boot 
from. To boot from a tape, you must specify the device name explicitly, as in 'b ar()'. 

No label found. 

No label found ~ attempting boot anyway. 

The monitor or boot program is trying to boot from a disk, and can't find a valid label 
on the disk. This is best fixed by booting a copy of diag(9>S) from a different device 
(for example, network disk or tape) and using the 'verify label' and 'label' commands. 
See the warning under "Corrupt label" above. This error might also be caused by 
missing or bad disk cables. 

No more file slots 

The current program is using the standalone I/O library and has opened too many dev- 
ices or files. 

not a directory 

The current program (possibly the boot program) has tried to open a disk or network 
disk file with a pathname, but one of the names in the path is not a directory. 

name not found 

The boot program has searched for the requested file, but cannot find it. You can retry 
your boot command, using "*" instead of name, to get a list of the names that exist in 
that directory. 

null path 

The current program (possibly the boot program) has tried to open a file whose name is 
empty. 

PageMap aaaaaa \»s\\ xxxxxxxx^. 

I'he monitor is displaying or modifying a page map entry because you entered a 'p' 
command, aaaaaa is the virtual memory address whose map entry is being examined. 
$9 is the segment map entry which is being used to map this page map entry and page. 
^xxxxxxx is the page map entry itself. You can enter a space and type 'RETURN' to 
get back to command mode 

Parity Bus Error ... 

See "Bus Error...". The attempted access was probably valid, but was cancelled 
because the preceding access was to memory with bad parity. (Parity errors are 
reported on the memory cycle after the failing cycle.) If neither "Upper Byte" nor 
"Lower Byte" is reported, the parity on both bytes was invalid. The access address 
printed in the Bus Error message is probably not relevant to the parity error. There is 
no general way to recover from this error; a good starting point, though, is to boot 
parBCian{2S), which will search all of memory for parity errors. 

Please clear keyboard to begin 

The monitor is trying to listen for your typing on the keyboard, but cannot tell which 
shift keys are down until you release all the locking keys (Caps Lock and Shift Lock). 
Once it has seen all the keys released, it can then track the movements of the keys and 
typing will work. 
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Please start it, if necessary, -OR- press any key to quit. 
See "Waiting for disk to spin up...". 

Possible boot devices: 

You have asked for a list of boot devices with the 'b ?' command. 

Protection Bus Error ... 

See "Bus Error...". The attempted access was invalid because your program is not per- 
mitted to access the addressed data in this way; for example, writing to that page is 
disallowed. 

ROM Rev z, mm memory installed 

The monitor is identifying its revision level and the system configuration as part of the 
power-on sequence, z is a letter or phrase indicating which particular version of the 
monitor is installed; mm shows how much memory was found during system 
configuration at power-on. If an even number of megabytes is installed, mm is 
displayed as "nnMB"; otherwise as "nnnnKB". 

Retensing... 

The monitor is attempting to boot from an Archive tape. Its first attempt failed, so it 
is retensing the tape (winding all the tape from one reel to the other), which makes it 
much more likely to succeed. 

Seek not from beginning of file 

The current program is using the standalone I/O library and has tried to do an unsup- 
ported seek operation. 

SegMap aaaaaa: zx! 

The monitor is examining or changing the segment map in response to your recent *m* 
command. You can enter a space and type 'RETURN' to get back to command mode. 

Self Test completed successfully 

The monitor has completed its power-on self test without finding any hardware prob- 
lems. 

Self Test found a problem in something 

The monitor has completed its power-on self test and found a problem in some subsys- 
tem. Something describes the general location of the error. Further messages give more 
details; see "Wrote ..." and "Damage found...". 

Serial if'somt_number, Ethernet address n:n:n:n:n:n 

The monitor is identifying your machine's serial number and hardware Ethernet 
address as part of the power-on sequence. The hardware Ethernet address is taken 
from the ID PROM on the Sun-2 CPU board, and is given as a 6-byte hexadecimal 
value with a colon between each byte. A typical Ethernet address might be 
"8:0:20:1:1:A3\ 

Short read 

The boot program is trying to boot a program from disk or net disk. It has located the 
program, but encountered an error while reading it into memory. 

Size: text -\- data + bss bytes 

The boot program is loading iu the program you requested. Text, data, and bss are the 
sizes of the three sections of the program; they are printed as each is read into memory. 
After finishing display of this message, the boot program begins execution of your pro- 
gram; further messages can come from it instead of from the boot program or monitor. 

Sun Workstation, Model Sun-1/lOOU or Sun-l/150U, keyb keyboard 

The Model lOOU or 150U workstation has just been powered on, or you entered a 'kb' 
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command, and the monitor is identifying its configuration. Keyb is either VTIOO or 
Two-tone, depending which keyboard your monitor ROMs support. 

Sun Workstation, Model Sun-2/120 or Sun-2/170, Sun-2 keyboard 

The Model 120 or 170 workstation has just been powered on, or you entered a 'kb' 
command, and the monitor is identifying its configuration. 

Timeout Bus Error ... 

See "Bus Error...". The attempted access was invalid because no device responded at 
the addressed location. This most often happens for Multibus references. The program 
was probably trying to access a device or section of memory which does not exist, or 
which has gotten into a hung state. If this occurs in response to a boot command, the 
device you are trying to boot from is not installed in your system. 

tm: error nn during config of ctlr cc 

tm hard err nn 

tm: no response from ctlr cc 

A standalone program (possibly the boot program) is trying to use the Tapem aster 
nine- track tape drive, and has encountered an error. This could be caused by a bad or 
missing tape, loose or misplugged cables, incorrect jumpers on the Tapemaster con- 
troller board, or hardware errors. Nn can be decoded by looking in the Tapemaster 
Product Specification. 

Unknown device 

The current program (possibly the boot program) has tried to use a device which is 
unknown to the standalone I/O system. 

Upper Byte Parity Bus Error ... 

See "Bus Error..." and "Parity...". The preceding access was to a word in memory 
with a parity error in its upper byte. 

ut i, uoo, uzabattdf nhbhaud, nnaaaaaa, necho 

The monitor is describing its console and serial port configuration in response to a 'u' 
command. / is the input device (k for keyboard, or a or b for a serial port); o is the 
output device (s for screen, or a or b); abaud and bbaud are the baud rates on the serial 
ports; aaaaaa is the address of the Zilog 8530 chip which implements the serial ports, 
and echo is 'e' if input echoing is enabled ("full duplex") or *ne* if disabled ("half 
duplex"). 

Using RS232 A input. 

The monitor did not find the Sun keyboard, so it is taking input from one of the serial 
ports on the back of the Workstation, marked "RS232 A". If this is unexpected, make 
sure that the keyboard is plugged into the correct socket on the workstation. The key- 
board must be plugged in before system power is turned on. If you connect a Sun key- 
board after this message appears, you can let the monitor know about the keyboard by 
entering the Abort sequence (hold down the upper left key on the Sun keyboard, and 
press *A'). The monitor will switch to using the Sun keyboard since that's where the 
Abort was typed. Then type *c' to continue whatever program was running when you 
aborted. 

If you don't want to use a Sun keyboard, connect a normal ASCII terminal to the 
"RS232 A" connector on the back panel. Configure the terminal for 9600 baud, no 
parity, one stop bit. Things that you type on the terminal will be displayed on the Sun 
video screen, if you have one, or on the terminal's screen. 
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Waiting for disk to spin up... 

The monitor is trying to boot from a disk. The disk is not ready, so the monitor is 
waiting in the hope that the disk is just starting to spin and will become ready soon. If 
you get this message when the power has been on for a while, your disk cables are 
probably loose or misconnected. 

Watchdog reset! 

The current program has stopped executing with a "double bus fault". This is 
explained in detail in the Motorola 68010 manual; the two most common causes are 
that low memory (interrupt vectors) has been overwritten, or the system stack pointer 
is pointing to an invalid address. There is a serious bug in your program if this occurs. 

What? 

You typed a command that the monitor does not recognize. Try again. 

Wrote wdata at address addr, but read rdata 

The monitor has completed its power-on self test and found a problem in some subsys- 
tem. The preceding "Self Test found a problem..." message describes which part of the 
system was in error. This message gives more details about the error. Wdata is the 
data that was written into part of the system, or which was expected to be there if the 
system was functioning normally. Addr is the address where the data was read and/or 
written. For memory errors, this is a physical memory address; for other errors, the 
interpretation of this field depends on what subsystem was being tested. Rdata is the 
data that was read back from addr and was found to be invalid because it was not the 
same as wdata. This information should be written down and reported to your local 
Field Service organization, or to Sun Microsystems Field Service. See the section Non- 
Critical Errors From Self Test above. 

xy: error nn cmd zx 

xy: error nn bno 66666 

xy: init error zx 

The monitor is trying to boot from the Xylogics disk and has encountered an error. 
The command being executed at the time is defined by the hexadecimal value zx (if 
present); the block number is 66666 (if present), and the particular error is encoded as 
nn. The error and command can be decoded by looking in the Xylogics manual. 

xy: no bad block info 

The boot program is trying to read from the Xylogics disk, but can't find the informa- 
tion about bad blocks on the disk. It continues, but if the program attempts to read 
any bad blocks (which have been remapped to elsewhere on the disk), the attempt will 
fail. 

zero length directory 

A standalone program (possibly the boot program) is trying to read a file from disk, 
but one of the directories in the path name has no files in it. The file system should be 
checked and fixed by using fsck{8). 
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NAME 

intro - introduction to system maintenance and operation commands 

DESCRIPTION 

Thb section contains information related to system bootstrapping, operation and maintenance 
and describes all the server processes and daemons which run on the system. 

Disk formatting and labelling is done by diag{SS) which participates in most system bootstraps. 
Bootstrapping of the system is described in reboot(S). The standard set of commands run by the 
system when it boots is described in rc(8). Related commands include ones to check the con- 
sistency of file systems f8ck{S), mount and unmount file systems mount{S) and umount(S), add 
swap devices 8wapon{8), cause all outstanding disk I/O to complete 8ync(S), shutdown or reboot a 
running system 8hutdown(S), haU{S), and reboot(8), set the time on a machine from the time on 
another machine rdate{8). 

Creation of file systems is dbcussed in mA;/a(8) and newf8{S). File system performance parameters 
are adjustable with tune/s(8). File system saves and restores are described in dump{S) and 
re8tore{S). 

Procedures for adding new users to a system are described in addu8er{S) using vipw(S). 

Other programs useful when the system crashes or hardware is broken include gxte8t{8S) which 
tests the frame buffer on a workstation, imemte8t{8S) which tests the memory, cra9A(8S) which 
describes what happens when the system crashes, 8avecore(8) and analyze{8) which can be used to 
analyze system crash dumps. Occasionally useful as adjuncts to the f8ck{8) file system repair pro- 
gram are c/rt(8), dcheck(8), icheck{8), and ncheck(8). 

Configuring a new version of the UNIX kernel requires using the program config{8); major system 
bootstraps often require the use of mkproto{8). New devices are made in the /dev directory when 
device drivers are added tp the system by using the makedev(8) and mknod(8) commands. If you 
have source, you will use the in8tall(8) command to reinstall freshly compiled programs, and cat- 
man(8) to reformat the pre-formatted version of the manual. 

Resource accounting is enabled by the accton{8) command, and summarized by 8a{8). Login time 
accounting is performed by ac(8). 

A number of service and daemon processes are described here. The cron{8) daemon forces 
delayed disk I/O to occur and runs periodic events (such as removing temporary files from the 
disk periodically). The dme8g{8) process is invoked by cron and keeps the system error log. The 
init{8) process is the initial process created when UNIX boots and manages the reboot process and 
creates the initial login prompts on the various system terminals through the services of getty{8). 
The Internet super-server inetd{8C) invokes all other internet servers as needed. These servers 
include the remote shell servers r8hd{8C) and rexecd{8C) the remote login server rlogind{8C) the 
FTP and TELNET daemons ftpd(8C) and telnetd{8C), the TFTP daemon tftpd(8C) and the mail 
arrival notification daemon com«a{(8C). Other network daemons include the 'load average/who is 
logged in' daemon rwhod(8C), the routing daemon routed(8C), and the mail daemon 8endmail{8). 

If network protocols are being debugged, then the protocol debugging trace program ^rp/(8C) is 
often useful. Remote magnetic tape access is provided by rsh and rmt(8C). Remote line printer 
access is provided by lpd{8) and control over the various print queues is had through /pc(8). 
Printer cost accounting is done through pac(8). 

Network host tables may be gotten from the ARPA NIC using gettabte{8C) and converted to 
UNIX usable format using htable{8). 
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LIST OF PROGRAMS 

Program Appears on Page 



ac 


ac.8 


accton 


sa.8 


adbgen 


adbgen.8 


add user 


adduser.8 


analyze 


analyze.8 


arp 


arp.Sc 


catman 


catman.8 


chown 


chown.8 


clri 


clri.8 


comsat 


comsat.8c 


config 


config.8 


crash 


crash .8s 


cron 


cron .8 


dcheck 


dcheck.8 


diag 


diag.88 


dmesg 


dmesg.8 


dump 


dump.8 


dumpfs 


dumpf8.8 


expire 


expire.8 


fastboot 


fastboot.8 


fasthalt 


fastboot.8 


fsck 


fsck.8 


ftpd 


ftpd .8c 


gettable 


gettable.8c 


getty 


getty. 8 


gxtest 


gxtest.8s 


halt 


halt.8 


htable 


htable.8 


icheck 


icheck.8 


ifconfig 


ifconfig.8c 


imemtest 


imemtest. 8s 


inetd 


inetd. 8c 


init 


init.8 


iostat 


iostat.8 


kgmon 


kgmon. 8 


Ipc 


lpc.8 


Ipd 


lpd.8 


MAKEDEV 


makedev.8 


makekey 


makekey .8 


mkfs 


mkfs.8 


mknod 


mknod .8 


mkproto 


mkproto.8 


mount 


mount.8 


ncheck 


ncheck. 8 


nd 


nd.8c 


netstat 


netstat.8 


newaliases 


newaliases. 8 


newfs 


newfs.8 


pac 


pac. 8 


pstat 


pstat.8 


quot 


quot .8 



Description 

login accounting 

system accounting 

generate adb script 

procedure for adding new users 

Virtual UNIX postmortem crash analyzer 

address resolution display and control 

create the cat files for the manual 

change owner 

clear i-node 

biff server 

build system configuration files 

what happens when the system crashes 

clock daemon 

file system directory consistency check 

General-purpose stand-alone utility package 

collect system diagnostic messages to form error log 

incremental file system dump 

dump file system information 

remove outdated news articles 

reboot/halt the system without checking the disks 

reboot/halt the system without checking the disks 

file system consistency check and interactive repair 

DARPA Internet File Transfer Protocol server 

get NIC format host tables from a host 

set terminal mode 

stand alone test for the Sun video graphics board 

stop the processor 

convert NIC standard format host tables 

file system storage consistency check 

configure network interface parameters 

stand alone memory test 

internet services daemon 

process control initialization 

report I/O statistics 

generate a dump of the operating system's profile buffere 

line printer control program 

line printer daemon 

make system special files 

generate encryption key 

construct a file system 

build special file 

construct a prototype file system 

mount and dismount file system 

generate names from i-numbers 

network disk control 

show network status 

rebuild the data base for the mail aliases file 

construct a new file system 

printer/plotter accounting information 

print system facts 

summarize file system ownership 
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re 


re. 8 


rdate 


rdate.8 


reboot 


reboot. 8 


recnews 


reenews.8 


renice 


renice.8 


restore 


restore.8 


rexecd 


rexecd .8c 


rlogind 


rlogind .8c 


rmail 


rmail.8 


rmt 


rmt.8e 


route 


route.Sc 


routed 


routed. 8c 


rshd 


rshd. 8c 


rwhod 


rwhod.Sc 


sa 


sa.8 


savecore 


savecore. 8 


sendmail 


send mail. 8 


sendnews 


sendnews.8 


shutdown 


shutdown. 8 


sticky 


sticky. 8 


swapon 


swapon .8 


sync 


sync. 8 


syslog 


syslog.8 


telnetd 


telnetd .8c 


tftpd 


tftpd. 8c 


timed 


timed. 8c 


trpt 


trpt.8e 


tunefs 


tunef8.8 


umount 


mount.8 


update 


update.8 


uuclean 


uuclean.Sc 


uurec 


uurec. 8 


vipw 


vipw. 8 


vmstat 


vmstat.8 



command script for auto-reboot and daemons 

set system date from a remote host 

UNIX bootstrapping procedures 

receive unprocessed articles via mail 

alter priority of running processes 

incremental file system restore 

remote execution server 

remote login server 

handle remote mail received via uucp 

remote magtape protocol module 

manually manipulate the routing tables 

network routing daemon 

remote shell server 

system status server 

system accounting 

save a core dump of the operating system 

send mail over the internet 

send news articles via mail 

close down the system at a given time 

executable files with persistent text 

specify additional device for paging and swapping 

update the super block 

log systems messages 

DARPA TELNET protocol server 

DARPA Trivial File Transfer Protocol server 

DARPA Time server 

transliterate protocol trace 

tune up an existing file system 

mount and dismount file system 

periodically update the super block 

uucp spool directory clean-up 

receive processed news articles via mail 

edit the password file 

report virtual memory statistics 
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NAME 

ac - login accounting 

SYNOPSIS 

/usr/etc/ae | -w wtmp | ( -P | ( -d ] ( people | ... 

DESCRIPTION 

Ac produces a printout giving connect time for each user who has logged in during the life of the 
current wtmp file. A total is also produced. 

The accounting file /usr/adm/wtmp is maintained by init and login. Neither of these programs 
creates the file, so if it does not exist no connect-time accounting is done. To start accounting, it 
should be created with length 0. On the other hand if the file is left undisturbed it will grow 
without bound, so periodically any information desired should be collected and the file truncated. 

OPTIONS 

— w specifies an alternate wtmp file. 

-p prints individual totak; without this option, only totals are printed. 

— d printout for each midnight to midnight period. Any people will limit the printout to only 
the specified login names. If no wtmp file is given, /usr/adm/wtmp is used. 

FILES 

/usr/adm/wtmp 

SEE ALSq 

ini^(8), sa(8), login(l), utmp(5). 



Last change: 4 February 1983 Sun Release 1.1 



ADBGEN(8) MAINTENANCE COMMANDS ADBGEN(8) 



NAME 

adbgen - generate adb script 

SYNOPSIS 

/usr/Ub/adb/adbgen file.adb ... 

DESCRIPTION 

Adbgen makes it possible to write adb{l) scripts that do not contain hard-coded dependencies on 
structure member offsets. The input to adbgen is a file named file,Bdb which contains adbgen 
header information, then a null line, then the name of a structure, and finally an adb script. 
Adbgen only deals with one structure per file; all member names are assumed to be in this struc- 
ture. The output of adbgen is an adb script in file. Adbgen operates by generating a C program 
which determines structure member offsets and sizes, which in turn generates the adb script. 

The header lines, up to the null line, are copied verbatum into the generated C program. Typi- 
cally these include C #include statements to include the header files containing the relevant 
structure declarations. 

The adb script part may contain any valid adb commands (see adb{l)), and may also contain 
adbgen requests, each enclosed in {}s. Request types are: 

1 Print a structure member. The request form is {member Jormat). Member is a member 
name of the structure given earlier, and format is any valid adb format request. For 
example, to print the p_pid field of the proc structure as a decimal number, you would 
write {p_pid,d}. 

2 Reference a structure member. The request form is {* member, base). Member is the 
member name whose value is desired, and base is an adb register name which contains the 
base address of the structure. For example, to get the p_pid field of the proc structure, 
you would get the proc structure address in an adb register, say <f, and write 
{*p_pld,<f}. 

3 Tell adbgen that the offset is ok. The request form is {OFFSETOK}. This is useful 
after invoking another adb script which moves the adb dot. 

4 Get the size of the structure. The request form is {SIZEOF}. Adbgen replaces this 
request with the size of the structure. This is useful in incrementing a pointer to step 
through an array of structures. 

5 Get the offset to the end of the structure. The request form is {END}. This is useful at 
the end of the structure to get adb to align the dot for printing the next structure 
member. 

Adbgen keeps track of the movement of the adb dot and emits adb code to move forward or back- 
ward as necessary before printing any structure member in a script. Adbgen's model of the 
behavior of adb's dot is simple: it is assumed that the first line of the script is of the form 
struct_addre88/ adb text and that subsequent lines are of the form -f /adb text. This causes the 
adb dot to move in a sane fashion. Adbgen does not check the script to ensure that these limita- 
tions are met. Adbgen also checks the size of the structure member against the size of the adb for- 
mat code and warns you if they are not equal. 

EXAMPLE 

If there were an include file x.h which contained: 

struct x { 

char *x_cp; 

char x_c; 

int x_i; 



}; 
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Then an adbgen file (call it script. adb) to print it would be: 
#include "x.h" 

X 

./"x.cp" 16t''x_c''8t''x_i''n{x_cp,X}{x_c,C} {x_i,D} 
After running adbgen the output file script would contain: 

./''x_cp''16t''x_c''8t''x_i''nXC+ D 
To invoke the script you would type: 

x$<script 

DIAGNOSTICS 

Warnings about structure member sizes not equal to adb format items and complaints about badly 
formatted requests. The C compiler complains if you reference a structure member that does not 
exist. It also complains about & before array names; these complaints may be ignored. 

FILES 

/usr/lib/adb/* adb scripts for debugging the kernel 

SEE ALSO 

adb(l), Using ADB to Debug the UNIX Kernel 

BUGS 

Adb syntax is ugly; there should be a higher level interface for generating scripts. 

Structure members which are bit fields cannot be handled because C will not give the address of a 
bit field. The address is needed to determine the offset. 
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NAME 

adduser - procedure for adding new users 

DESCRIPTION 

A new user must choose a login name, which must not already appear in /etc/paaswd. An account 
can be added by editing a line into the passwd file; this must be done with the password file 
locked, for example, by using vipw{8). 

A new user is given a group and user id. User id's should be distinct across a system, since they 
are used to control access to files. Typically, users working on similar projects will be put in the 
same group. System staff is group '10' for historical reasons, and the super-user is in this group. 

A skeletal account for a new user 'esmerelda' would look like: 

esmerelda :x 235 1 20 1 & Featherstonehaugh t /usr /esmerelda x /bin/csh 

Fields in the password file have the following meanings: 

1. Login name ('esmerelda'). 

2. Encrypted password. Set the user's password with pa88wd{l). 

3. User ID. 

4. Group ID. 

5. This field is called the 'GCOS' field (from earlier implementation of UNIX) and is traditionally 
used to hold the user's full name. Some installations have other information encoded in this 
field. From this information we can tell that esmerelda's real name is 'Esmerelda Feather- 
stonehaugh*. The & here is a shorthand for the user's login name. 

6. User's home directory. 

7. Initial shell which this user will see on login. If this field is empty, 8h{l) is used as the initial 
shell. 

It is useful to give new users some help in getting started, supplying them with a few skeletal files 
such as .profile if they use '/bin/sh', or .cshrc and .login if they use '/bin/csh'. New users should 
be given copies of these files which, for instance, arrange to use t8et{l) automatically at each 
login. 

FILES 

/etc/passwd password file 

SEE ALSO 

passwd(l), chsh(l), passwd(5), vipw(8) 
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NAME 

analyze - Virtual UNIX postmortem crash analyzer 

SYNOPSIS 

/usr /etc/analyse [ -s swapfile ] [ -f ] | -m 1 [ -d 1 I -D ] ( -v | corefile [ system ] 

DESCRIPTION 

Analyze is the post-mortem analyzer for the state of the paging system. In order to use analyze 
you must arrange to get a image of the memory (and possibly the paging area) of the system after 
it crashes (see cra9A(8S)). 

The analyze program reads the relevant system data structures from the core image file and 
indexing information from /vmunix (or the specified file) to determine the state of the paging 
subsystem at the point of crash. It looks at each process in the system, and the resources each is 
using in an attempt to determine inconsistencies in the paging system state. Normally, the out- 
put consists of a sequence of lines showing each active process, its state (whether swapped in or 
not), its pObr, and the number and location of its page table pages. Any pages which are locked 
while raw i/o is in progress, or which are locked because they are intransit are also printed. 
(Intransit text pages often diagnose as duplicated; you will have to weed these out by hand.) 

The program checks that any pages in core which are marked as not modified are, in fact, identi- 
cal to the swap space copies. It also checks for non-overlap of the swap space, and that the core 
map entries correspond to the page tables. The state of the free list is also checked. 

Options to analyze: 

-D causes the diskmap for each process to be printed. 

— d causes the (sorted) paging area usage to be printed. 

-f which causes the free list to be dumped. 

— m causes the entire coremap state to be dumped. 

-V (long unused) which causes a hugely verbose output format to be used. 

In general, the output from this program can be confused by processes which were forking, swap- 
ping, or exiting or happened to be in unusual states when the crash occurred. You should exam- 
ine the flags fields of relevant processes in the output of a p8tat{S) to weed out such processes. 

It is possible to look at the core dump with adb if you do 

adb -k /vmunix /vmcore 

FILES 

/vmunix default system namelist 

SEE ALSO 

adb(lS), ps(l), crash(8S), pstat(8) 

AUTHORS 

Ozalp Babaoglu and William Joy 

DIAGNOSTICS 

Various diagnostics about overlaps in swap mappings, missing swap mappings, page table entries 
inconsistent with the core map, incore pages which are marked clean but difl'er from disk-image 
copies, pages which are locked or intransit, and inconsistencies in the free list. 

It would be nice if this program analyzed the system in general, rather than just the paging sys- 
tem in particular. 
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NAME 

arp - address resolution display and control 

SYNOPSIS 

arp hostname 

arp -a [ vmunix ] \ kmem \ 

arp -d hostname 

arp -8 hostname ether_addr [ temp ] { pub ] 

arp 't filename 

DESCRIPTION 

The arp program displays and modifies the Internet-to-Ethernet address translation tables used by 
the address resolution protocol ( arp(4p)). 

With no flags, the program displays the current ARP entry for hostname. With the -a flag, the 
program displays all of the current ARP entries by reading the table from the file kmem (default 
/dev/kmem) based on the kernel file vmuniz (default /vmunix). 

With the -d flag, a super-user may delete an entry for the host called hostname. 

The -■ flag is given to create an ARP entry for the host called hostname with the Ethernet 
address etherjaddr. The Ethernet address is given as six hex bytes separated by colons. The 
entry will be permanent unless the word temp is given in the command. If the word pub is 
given, the entry will be "published", e.g., this system will respond to ARP requests for hostname 
even though the hostname is not its own. 

The -f flag causes the file filename to be read and multiple entries to be set in the ARP tables. 
Entries in the file should be of the form 

hostname etherjaddr [ temp ] [ pub ) 

with argument meanings as given above. 

SEE ALSO 

arp(4p), ifconfig(8c) 
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NAME 

catmao - create the cat files for the manual 

SYNOPSIS 

/usr/etc/catman ( -p ] [ -n ] [ -w ] [ sections ] 

DESCRIPTION 

Catman creates the preformatted versions of the on-line manual from the nroff input files. Each 
manual page is examined and those whose preformatted versions are missing or out of date are 
recreated. If any changes are made, catman recreates the /usr/lib/whatis database. 

If there is one parameter not starting with a '-', it is take to be a list of manual sections to look 
in. For example 

caiman 123 

only updates manual sections 1, 2, and 3. 

OPTIONS 

-n Do not create /usr/llb/whatls. 

— p Print what would be done instead of doing it. 

-w Only create the /uar/lib/whatb database. No manual reformatting is done. 

FILES 

/usr/man/man?/*.* raw (nroff input) manual sections 

/usr/man/cat?/*.* preformatted manual pages 

/usr/lib/makewhatis commands to make whatis database 

SEE ALSO 

man(l) 
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NAME 

chown - change owner 

SYNOPSIS 

/etc/chown -t owner file . . . 

DESCRIPTION 

Cf^own changes the owner of the files to owner. The owner may be either a decimal UID or a 
login name found in the password file. 

Only the super-user can change owner, in order to simplify as yet unimplemented accounting pro- 
cedures. 

OPTIONS 

-f Do not report errors. 

FILES 

/etc/passwd 

SEE ALSO 

chgrp(l), chown(2), passwd(5), group(5) 



Sun Release 1.1 Last change: 27 March 1982 11 



CLRI ( 8 ) MAINTENANCE COMMANDS CLRI ( 8 ) 



NAME 

clri - clear i-node 

SYNOPSIS 

/etc/ clri filesystem i-n umber ... 

DESCRIPTION 

N.B.t Clri is obsoleted for normal file system repair work by f8ck{S). 

Clri writes zeros on the i-nodes with the decimal i-numbers on the filesystem. After clri, any 
blocks in the affected file will show up as 'missing' in an icheck{8) of the filesystem. 

R^sad and write permission is required on the specified file system device. The i-node becomes 
al|pcatable. 

The primary purpose of this routine is to remove a file which for some reason appears in no direc- 
tory. If it is used to zap an i-node which does appear in a directory, care should be taken to track 
down the entry and remove it. Otherwise, when the i-node is reallocated to some new file, the old 
eiJKry will still point to that file. At that point removing the old entry will destroy the new file. 
The new entry will again point to an unallocated i-node, so the whole cycle is likely to be 
repeated again and again. 

SEE ALS^ 

ic|f'pck(8) 

BUGS 

If the file is open, clri Is likely to be ineffective. 
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NAME 

comsat - biff server 

SYNOPSIS 

/uBr/etc/in.comsat 

DESCRIPTION 

Comsat is the server process which listens for reports of incoming mail and notifies users who have 
requested to be told when mail arrives. It is invoked as needed by inetd{8C), and times out if 
inactive for a few minutes. 

Comsat listens on a datagram port associated with the "biff" service specification (see 8ervices{b)) 
for one line messages of the form 

user®mail box-offset 

If the user specified is logged in to the system and the associated terminal has the owner execute 
bit turned on (by a "biff y"), the offset is used as a seek offset into the appropriate mailbox file 
and the first 7 lines or 560 characters of the message are printed on the user's terminal. Lines 
which appear to be part of the message header other than the "From", "To", "Date", or "Sub- 
ject" lines are not printed when displaying the message. 



FILES 



/etc/utmp to find out who's logged on and on what terminals 



SEE ALSO 

bit(l) 

BUGS 

The message header filtering is prone to error. 

Users should be notified of mail which arrives on other machines than the one they are currently 
logged in to. 

The notification should appear in a separate window so it does not mess up the screen. 
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NAME 

config - build system configuration files 

SYNOPSIS 

/usr/ete/eonflg ( -p J config_JUe 

DESCRIPTION 

Config builds a set of system configuration files from a short file which describes the sort of sys- 
tem that is being configured. It also takes as input a file which tells config what files are needed 
to generate a system. This can be augmented by a configuration-specific set of files that give 
alternate files for a specific machine, (see the FILES section below) Specifying the -p option to 
cofifig configures a system for profiling (see kgmon{S) and gprof{l)). 

R|fn config from the conf subdirectory of the system source (in a Sun environment, from 
IfUsfconf). Confix assumes that there is already a directory ../config_file created and it places all 
itfii output files in there. The output of config consists of several files: ioconf.c, which contains a 
d|»||(cription of I/O devices attached to the ^stem; a makefile, which is a file used by make{l) in 
building the system; a set of header files which contain the number of various devices that will be 
ccipipiled into the system; and a set of swap configuration files which contain definitions for the 
di^Jc areas to be used for swapping, the root file system, argument processing, and system dumps. 

After running confix, you must then change directory to the directory in which the new makefile 
was created, and use make to create the dependency tree for the new system: 

# cd ,,/ Sy8tem__Name 

# make depend 

Config reminds you of this when it completes. 

If you get any other error messages from confix, you should fix the problems in your configuration 
file and try again. If you try to compile a system that had configuration errors, you will probably 
not succeed. 

CONFIG FILE FORMAT 

In the following descriptions, a number can be a decimal integer, a whole octal number or a whole 
hexadecimal number. Hex and octal are specified to confix in the same way they are specified to 
the C compiler, a number starting with "Ox" is a hex number and a number starting with just a 
"0" is an octal number. When specifying the timezone, you may also use floating point numbers. 

Comments are specified in a config file with the character "#". All characters from a "#" to the 
end of a line are ignored. 

Lines beginning with tabs are considered continuations of the previous line. 

Lines of the configuration file can be one of two basic types. First, there are lines which describe 
general things about your system: 

machine type 

This is system is to run on the machine type specified. Only one machine type can appear 
in the config file. The legal type for a Sun system is sun. 

cpu "^type^ 

This system is to run on the cpu type specified. For a Sun system, "^type"* is ''SUN2'' (note 
that the double quotes are part of the designation). 

ident name 

Gives the system identifier — a name for the machine or machines that run this kernel. 
name must be enclosed in double quotes if it contains both letters and numbers. 

timesone number [ dst ] 

Specifies the timezone you are in. This is measured in the number of hours west of GMT 
you are. 5 is EST, 8 is PST. Negative numbers indicate hours east of GMT. If you specify 
dst, the system will operate under daylight savings time. 
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maxusers number 

The maximum expected number of simultaneously active user on this system is number. 
This number is used to size several system data structures. 

options optliat 

Compile the listed options into the system. Options in this list are separated by commas. 
There is a list of options that you may specify in the generic makefile. A line of the form 
"options FUNNY.HAHA" yields -DFUNNY -DHAHA to the C compiler. An option may be 
given a value, by following its name with "=" then the value enclosed in (double) quotes. 
None of the standard options use such a value. 

conflg sysname config^^clauses... 

Generate a system with name sysname and configuration as specified in config- clauses. The 
eydname is used to name the resultant binary image and per-system swap configuration files. 
The config_clause8 indicate the location for the root file system, one or more disk partitions 
for swapping and paging, a disk partition to which system dumps should be made, and a 
disk partition on which execve argument lists should be constructed. All but the root device 
specification may be omitted, config will fill them in with default values as described below. 

root A root device specification is of the form root on xyOd. If a specific partition is 
omitted — for example, if only root on xyO is specified — the "a" partition is 
assumed. When a generic system is being built, no root specification should be 
given; the root device will be defined at boot time by prompting the console. 

swap Swap device specifications have two possible forms. If a generic swap configuration 
is required, the clause swap generic should be specifed. Otherwise, if a single par- 
tition is to be used for swapping, one may specify swap on xyOh. If multiple parti- 
tions are to be interleaved one should specify something of the form swap on xyO 
and xyl and xylg. If no swap specification is given, config assumes swapping 
should be done on the "b" partition of the root device. Swapping areas may be 
almost any size and multiple swap partitions of varying size may be interleaved. 
Partitions used for swapping are sized at boot time by the system; to override 
dynamic sizing of a swap area the number of sectors in the swap area can be 
specified in the config file. For example, swap on xyOh size 99999 would configure a 
swap partition with 99999 sectors. 

args The partition to be used for argument list processing may be specified with a clause 
of the form args on xylb. If no argument device is specified, the first swap parti- 
tion specified is used. If a device is specified without a particular partition, the "b" 
partition is assumed. If a generic system is being built, no argument device should 
be specified; the argument device will be assigned to the swap device dynamically 
configured at boot time. 

dumps The location to which system dumps are sent may be specified with a clause of the 
form dumps on xyl. If no dump device is specified, the first swap partition 
specified is used. If a device is specified without a particular partition, the "b" par- 
tition is assumed. If a generic configuration is to be built, no dump device should 
be specified; the dump device will be assigned to the swap device dynamically 
configured at boot time. 

Dumps are placed at the end of the partition specified. Their size and location is 
recorded in global kernel variables dumpsize and dumplo, respectively, for use by 

savecore{S). 

Device names specified in configuration clauses are mapped to block device major numbers 
with a file / sysf con// devices.machine, where machine is the machine type previously 
specified in the configuration file. If a device name to block device major number mappfng 
must be overridden, a device specification may be given in the form miv}<>' ^ minor y. 
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The second group of lines in the configuration file describe which devices your system has and 
what they are connected to (for example, I have a Xylogics xy450 on the Multibus). These lines 
have the following format: 

devjtype dtv_name at conjiev more_info 

Devjtype is either tape, disk, controUer, device, or pseudo-device. These types have the fol- 
lowing meanings: 

controller 

b a Multibus disk controller or a Multibus tape controller. 

disk or tape 

are devices connected to a controller. 

device 

is something that plugs into the Multibus, like a cartridge tape interface. 

pseudo-device 

is something which should be conditionally loaded, but is not really a device. 
Current examples are the pseudo-tty driver and various network subsystems. (For 
pseudo-devices, more_info may be specified as an integer, that gives the value of 
the symbol defined in the header file created for that device, and is generally used 
to indicate the number of instances of the pseudo-device to create. If you load a 
subsystem you will probably find it convenient to enable conditional code using an 
options specification. 

devjname is the name of the device you are specifying. If it is not a pseudo-device, you must give 
a number afterwards (for example, xycO for a Xylogics controller, or arO for an Archive quarter- 
inch tape controller). 

Conjiev is what the device you are specifying is connected to. For example, disk xyl is con- 
nected to controller xycO. 

more_info is a sequence of the following: 

csr addr 

Specifies the csr (command and status registers) for a device. Must be specified for 
all Multibus tape and disk controllers and all devices connected to the Multibus. 
Make certain that you put a leading zero on the address so that it will be inter- 
preted as an octal number. 

drive number 

For a disk or tape, specifies which drive this is. 

flags number 

These flags are passed to the device driver at system initialization time. 

priority level 

For devices which interrupt on the Multibus, specifies the interrupt level at which 
the device operates. 

The easiest way to understand config files it to look at a working one and modify it to suit your 
system. A good sample is provided in the Installing UNIX for tke First Time chapter of the Sys- 
tem Installation and Maintenance Guide at the beginning of this manual. In the example, all lines 
are explained. 

A ? may be substituted for a number in two places and the system will figure out what to fill in 
for the ? when it boots. You can put question marks on a con_dev (e.g. at mba?), or on a drive 
number (e.g. drive ?) This allows redundancy, as a single system can be built which will reboot on 
different hardware configurations. 
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FILES 

/sys/conf/GENERIC generic config file for Sun systems 

/sys/conf/README file describing how to make a new kernel 

/sys/conf/makefile.sun generic makefile for Sun systems 

/sys/conf/files list of common files system is built from 

/sys/conf /files. sun list of Sun-specific files 

/sys/conf/devices.sun name to major device mapping file for Sun systems 

SEE ALSO 

The SYNOPSIS portion of each device entry in the section 4 pages of the System Interface 
Manual. 

In the System Manager's Manual: 

Kernel Configuration in the Installing UNIX for the First Time chapter. 
Building Sun Workstation Kernels in the Tutorials section 



BUGS 



The line numbers reported in error messages are usually off by one. 

The 'make depend' currently generates a few spurious error messages, for example: 

'../sun/locore.s: no such file or directory". Ignore these. 
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NAME 

crash - what happens when the system crashes 

DESCRIPTION 

This section explains what happens when the system crashes and how you can analyze crash 
dumps. 

When the system crashes voluntarily it prints a message of the form 
panic: why i gave up the ghost 

on the console, takes a dump on a mass storage peripheral, and then invokes an automatic reboot 
procedure as described in reboot(S). Unless some unexpected inconsistency is encountered in the 
state of the file systems due to hardware or software failure the system will then resume multi- 
user operations. 

The system has a large number of internal consistency checks; if one of these fails, then it will 
panic with a very short message indicating which one failed. 

The most common cause of system failures is hardware failure, which can reflect itself in different 
ways. Here are the messages which you are likely to encounter, with some hints as to causes. 
Left unstated in all cases is the possibility that hardware or software error produced the message 
in some unexpected way. 

lO err in push 
hard lO err in swap 

The system encountered an error trying to write to the paging device or an error in read- 
ing critical information from a disk drive. You should fix your disk if it is broken or 
unreliable. 

timeout table overflow 

This really shouldn't be a panic, but untU we fix up the data structure involved, running 
out of entries causes a crash. If this happens, you should make the timeout table bigger. 

trap type %d, code=%d, pc=%x 

A unexpected trap has occurred within the system; the trap types are: 






reserved addressing fault 


1 


privileged instruction fault 


2 


reserved operand fault 


3 


bpt instruction fault 


4 


xfc in&truction fault 


5 


system call trap 


6 


arithmetic trap 


7 


ast delivery trap 


8 


segmentation fault 


9 


protection fault 


10 


trace trap 


11 


compatibility mode fault 


12 


page fault 


13 


page table fault 



The favorite trap types in system crashes are trap types 8 and 9, indicating a wild refer- 
ence. The code is the referenced address, and the pc at the time of the fault is printed. 
These problems tend to be easy to track down if they are kernel bugs since the processor 
stops cold, but random flakiness seems to cause this sometimes. 

init died 

The system initialization process has exited. This is bad news, as no new users will then 
be able to log in. Rebooting is the only fix, so the system just does it right away. 
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That completes the list of panic types you are likely to see. 

When the system crashes it writes (or at least attempts to write) an image of memory into the 
back end of the primary swap area. After the system b rebooted, the program 8avecore{8) runs 
and preserves a copy of this core image and the current system in a specified directory for later 
perusal. See 0avecore{S) for details. 

To analyze a dump you should begin by running a(/6(lS) with the -k flag on the core dump. 
Normally the command "'''(intstack-4)$c" will provide a stack trace from the point of the crash 
and this will provide a clue as to what went wrong. A more complete discussion of system debug- 
ging is impossible here. See, however, "Using ADB to Debug the UNDC Kernel". 

SEE ALSO 

adb(lS), analyze(8), reboot(8) 

Using ADB to Debug the UNIX Kernel 
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NAME 

cron - clock daemon 

SYNOPSIS 

/etc/cron 

DESCRIPTION 

Cron executes commands at specified dates and times according to the instructions in the file 
/u8r/lib/crontab. Since cron never exits, it should only be executed once. This is best done by 
running cron from the initialization process through the file /etc/ re; see init{S). 

/usr/lib/crontab consists of lines of six fields each. The fields are separated by spaces or tabs. 
The first five are integer patterns to specify the minute (0-59), hour (0-23), day of the month (1- 
31), month of the year (1-12), and day of the week (1-7 with l=Monday). Each of these patterns 
may contain a number in the range above; two numbers separated by a dash meaning a range 
inclusive; a list of numbers separated by commas meaning any of the numbers; or an asterisk 
meaning all legal values. The sixth field is a string that is executed by the shell at the specified 
times. A percent character in this field is translated to a new-line character. Only the first line 
(up to a % or end of line) of the command field is executed by the shell. The other lines are 
made available to the command as standard input. 

Here are a few example lines from /usr/Ub/crontab, to give you a better sense of the file's format: 

* * * calendar - 

15 ♦ * * /usr/etc/sa -s >/dev/null 

0,30 * * * * /usr/etc/dmesg - >>/usr/adm/messages 

15 4 * * * find /usr/preserve -mtime + 7 -a -exec rm -f {} ; 

10 4 * * * egrep 'SYSERR|refu8ed|unreachable' /usr/spool/log/syslog.O |mail Postmaster 

Cron examines /usr/lib/crontab under the following conditions: 

• At least once per hour (on the hour). 

• When the next command is to be run — cron looks ahead until the next command and sleeps 
until then. 

• When cron's process is sent a SIGHUP. This means that comeone who changes / uar/ lib/ crontab 
can get cron to look at it right away. 

You can also create the / usr/ adm/ cronlog file, if you wish. If the file exists, cron logs to it each 
time it executes an instruction from /usr/lib/crontab. You can thus use the cronlog file to make 
sure cron is running properly. The lines in the file consist of a timestamp, and process statement. 
Lines look something like this: 

Thu Mar 8 10:20:00 1984: /etc/dmesg - >>/usr/adm/message8 
Thu Mar 8 10:29:59 1984: /etc/atrun 

Thu Mar 8 10:30:00 1984: /etc/dmesg - >>/usr/adm/messages 
Thu Mar 8 10:39:59 1984: /etc/dmesg - >>/usr/adm/messages 

FILES 

/usr/lib/crontab Instruction file 

/usr/adm/cronlog Log file 

SEE ALSO 

crontab(5) 
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NAME 

dcheck - file system directory consistency check 

SYNOPSIS 

/uir/etc/dcheck [ -I numbers ] [ filesystem ] 

DESCRIPTION 

N.B.: Dcheck is obsoleted for normal consistency checking by f8ck{S). 

Dcheck reads the directories in a file system and compares the link-count in each i-node with the 
number of directory entries by which it is referenced. If the file system is not specified, dcheck 
checks a set of default file systems. 

Dcheck is fastest if the raw version of the special file is used, since the i-list is read in large 
chunks. 

OPTIONS 

-1 numbers 

Numbers is a list of i-numbers; when one of those i-numbers turns up in a directory, the 
number, the i-number of the directory, and the name of the entry are reported. 

FILES 

Default file ^stems vary with installation. 

SEE ALSO 

fsck(8), icheck(8), fs(5), clri(8), ncheck(8) 

DIAGNOSTICS 

When a file turns up for which the link-count and the number of directory entries disagree, the 
relevant facts are reported. Allocated files which have link-count and no entries are also listed. 
The only dangerous situation occurs when there are more entries than links; if entries are 
removed, so the link-count drops to 0, the remaining entries point to thin air. They should be 
removed. When there are more links than entries, or there is an allocated file with neither links 
nor entries, some disk space may be lost but the situation will not degenerate. 

BUGS 

Since dcheck is inherently two-pass in nature, extraneous diagnostics may be produced if applied 
to active file systems. 

Dcheck is obsoleted by fsck and remains for historical reasons. 
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NAME 

diag - General-purpose stand-alone utility package 

SYNOPSIS 

b 8tand/dU« 

DESCRIPTION 

Diag is a general-purpose stand-alone utility package containing a grab-bag of the kinds of tools 
needed for dbk initialization, testing, and file transfer. Diag supports the various SMD and ST-506 
disk controllers. 

Note: that diag can only be called from the Sun Workstation PROM monitor — diag is not a sys- 
tem utility. 

The most common use of diag is formatting and labelling a disk — see the format, label, and par- 
tition commands. 

Diag is interactive — it prompts for options and arguments. There are two phases to using diag: 
in the first phase, diag prompts for information about the type of disk drive and controller that it 
is working with, and essentially 'configures' itself to work with that disk and controller. At the 
end of this phase, diag tries to access the disk controller you have defined. If the attempt 
succeeds, diag gives you a status report on the disk and gives you a 'diag>' prompt; this signals 
the beginning of diag's second phase. If the attempt to access the controller fails (if the controller 
is mis-defined or non-existent, for example), you get a bus error message, and return to the 
PROM monitor. 

During diag^s second phase, you can use the commands listed below in response to the 'diag>' 
prompt. A specific diag command is called up by typing enough characters to uniquely identify 
the command. The commands that diag currently recognizes are: 

clear Sends a restore command to a disk. This is needed to manually reset disk errors. 

diag Re-initializes the diag program itself — goes back to phase one of the inititialization 

process described above. 

errors Toggles an option to report all errors as they occur. 

fix Formats a single track (Interphase 2180 controller) or sector (Xylogics SMD controller) 

of a disk. This sub-command b not available for use with Adaptec disk controllers 
(ST-506 interface). If the track/sector is already formatted, you are asked for 
confirmation in order to avoid destroying the data on the track/sector. 

format Formats a disk. 

help or ? Displays a list of the available commands. 

Info Toggles an option to report all disk activity as it completes. 

label Labels the disk. 

map Explicitly maps one track or sector to a different track or sector. Usually required for 

bad track mapping. The format command usually does this automatically. Note that, 
like the the fix command above, map is disk controller-dependent: you can map 
tracks with an Interphase controller, and sectors with Xylogics controllers, map is not 
available for use with Adaptec disk controllers (ST-506 interface). 

partition Creates, assigns, or modifies logical partition tables for a disk. The UNIX operating 
system requires logical partitions. The label command writes the partition map to the 
disk. There are standard partition tables for each type of disk that diag knows about. 

position Tests the disk by reading sectors from random positions on the disk. This command 
runs until the user aborts it by typing the letter 'a'. 

quit Quits from diag and returns to whoever called it up. 
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read Reads specified blocks from the disk. The read command prompts for the starting 

block number, number of blocks, and the block increment. The read command 
doesn't report the data it reads — it is intended for verifying that blocks are readable. 

seek Performs a seek test on the disk such that a seek is made to every cylinder and a seek 

is made to every possible cylinder distance. 

status Reports the ready status of each drive on the current controller. 

test Does a general disk test by writing random data to random positions on the disk and 

then verifying that the correct data can be read back. The test command destroys 
data on the disk. It runs until the user aborts the process by typing the letter 'a'. 

time Toggles an option to turn timing on and off. When timing is on, diag reports on how 

long things take — diag is less verbose in this state so it doesn't waste time displaying 
messages. 

verify Reads and displays the label from the disk. Shows the logical partition assignments. 
This is usually done automatically when the format command has labelled the disk. 

write Writes garbage data to specified blocks on the disk. The write command prompts for 

the starting block number, number of blocks, and the block increment. The write is 
intended for verifying that blocks are writeable. 

+ Adds two numbers and reports the result in decimal, hexadecimal, and as a disk 

address. 

— Subtracts two numbers and reports the result in decimal, hexadecimal, and as a disk 

address. 

Block numbers may be entered either as an absolute decimal block number, or as a disk address 
of the form cylinder/head/sector. 

Any diag command may be aborted by typing a *C (control-C). 
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NAME 

dmesg - collect system diagnostic messages to form error log 

SYNOPSIS 

/uBr/etc/dmesg [ - ] 

DESCRIPTION 

Dmesg looks in a system buffer for recently printed diagnostic messages and prints them on the 
standard output. The messages are those printed by the system when device (hardware) errors 
occur and (occasionally) when system tables overflow non-fatally. If the - flag is given, then 
dmesg computes (incrementally) the new messages since the last time it was run and places these 
on the standard output. This is typically used with cron{S) to produce the error log 
I Msr I admj messages by running the command 

/etc/dmesg - > > /usr/adm/messages 

every 10 minutes. 

FILES 

/usr/adm/messages error log (conventional location) 

/usr/adm/msgbuf scratch file for memory of - option 

BUGS 

The system error message buffer is of small finite size. As dmesg is run only every few minutes, 
not all error messages are guaranteed to be logged. This can be construed as a blessing rather 
than a curse. 

Error diagnostics generated immediately before a system crash will never get logged. 
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NAME 

dump - incremental file system dump 

SYNOPSIS 

/etc/dump { key { argument ... ] filesystem ] 

DESCRIPTION 

Dump copies to magnetic tape all files changed after a certain date in the filesystem. The key 
specifies the date and other options about the dump. Key consists of characters from the set 
0|23450780ni8dWne. 

0-^0 This number is the 'dump level'. All files modified since the last date stored in the file 
/etcfdumpdates for the same filesystem at lesser levels will be dumped. If no date is deter- 
mined by the level, the beginning of time is assumed; thus the entire filesystem is dumped if 
the option is used. 

f Place the dump on the next argument file instead of the tape. If file is of the form 
machine:device, dump to a remote machine. 

u If the dump completes successfully, write the date of the beginning of the dump on file 
I etcfdumpdates. This file records a separate date for each filesystem and each dump level. 
The format of f etcfdumpdates is readable by people, consisting of one free format record per 
line: filesystem name, increment level and ctime(S) format dump date, f etcfdumpdates may 
be edited to change any of the fields, if necessary. 

■ The size of the dump tape is specified in feet. The number of feet is taken from the next 
argument. When the specified size is reached, dump waits for reels to be changed. The 
default tape size is 2300 feet. 

d The density of the tape, expressed in BPI, is taken from the next argument. This is used in 
calculating the amount of tape used per reel. The default is 1600. 

W Dump tells the operator what file systems need to be dumped. This information is gleaned 
from the files f etc f dump dates and fetcffstab. The W option causes dump to print out, for 
each file system in f etcf dumpdates the most recent dump date and level, and highlights 
those file systems that should be dumped. If the W option is set, all other options are 
ignored, and dump exits immediately. 

w Is like W, but prints only those filesystems which need to be dumped. 

n Whenever dump requires operator attention, notify by means similar to a wall{l) ail of the 
operators in the group "operator". 

c Dump to cartridge tape instead of standard half-inch magnetic tape. 

b Specifies the blocking factor for the dump. The blocking factor is taken from the next argu- 
ment on the command line. The default blocking factor is 10. 

If no arguments are given, the key is assumed to be Ou and a default file system is dumped to the 
default tape. 

Dump requires operator intervention on these conditions: end of tape^ end of dump, tape write 
error, tape open error or disk read error (if there are more than a threshold of 32). In addition to 
alerting all operators implied by the n key, dump interacts with the operator on dump 's control 
terminal at times when dump can no longer proceed, or if something is grossly wrong. All ques- 
tions dump poses must be answered by typing "yes" or "no", appropriately. 

Since making a dump involves a lot of time and effort for full dumps, dump checkpoints itself at 
the start of each tape volume. If writing that volume fails for some reason, dump will, with 
operator permission, restart itself from the checkpoint after the old tafte has been rewound and 
removed, and a new tape has been mounted. 
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Dump tells the operator what is going on at periodic intervals, including usually low estimates of 
the number of blocks to write, the number of tapes it will take, the time to completion, and the 
time to the tape change. The output is verbose, so that others know that the terminal controlling 
dump is busy, and will be for some time. 

Now a short suggestion on how to perform dumps. Start with a full level dump 

dump Oun 

Next, dumps of active file systems are taken on a daily basis, using a modified Tower of Hanoi 
algorithm, with this sequence of dump levels: 

32 54769899... 
For the daily dumps, a set of 10 tapes per dumped file system is used on a cyclical basis. Each 
week, a level 1 dump is taken, and the daily Hanoi sequence repeats with 3. For weekly dumps, a 
set of 5 tapes per dumped file system is used, also on a cyclical basis. Each month, a level 
dump is taken on a set of fresh tapes that is saved forever. 



FILES 



/dev/rrplg default filesystem to dump from 

/dev/rmt8 default tape unit to dump to 

/etc/dumpdates new format dump date record 

/etc/fstab dump table: file systems and frequency 

/etc/group to find group operator 

SEE ALSO 

restore(8), dump(5), fstab(5) 

DLVGNOSTICS 

Many, and verbose. 

BUGS 

Sizes are based on 1600 BPI blocked tape; the raw magtape device has to be used to approach 
these densities. Fewer than 32 read errors on the filesystem are ignored. Each reel requires a new 
process, so parent processes for reels already written just hang around until the entire tape is 
written. 

It would be nice if dump knew about the dump sequence, kept track of the tapes scribbled on, 
told the operator which ta^e to mount when, and provided more assistance for the operator run- 
ning restor. 
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NAME 

dumpfs - dump file system information 

SYNOPSIS 

/usr/ete/dumpfB device 

DESCRIPTION 

Bumpfa prints out the super block and cylinder group information for the file system or special 



rice specified. The listing is very long and detailed. This command is useful mostly for finding 
ou|. certain file system information such as the file system block size and minimum free space per- 
centage. 

SEE ALSQ 

{M, tunef8(8), newfs(8), fsck(8) 
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NAME 

expire - remove outdated news articles 

SYNOPSIS 

/usr/local/Ub/news/expire ( -n newsgroups ] ( -I I | -I ) ( -v|/eye/ J ) ( -« days ] ( -« ) 
|-r||-h| 

DESCRIPTION 

Expire is normally started up by cron{S) every night to remove all expired news. If no news- 
groups are specified, the default is to expire all. 

Articles whose specified expiration date has already passed are considered expirable. 

OPTIONS 

-n newsgroups 

List of newsgroups to expire. Elements in the list of newsgroups must be separated by 
commas and/or spaces. 

-a archive articles in /usr/spool/oldnews. Articles are unlinked in the absence of the -a 

option. 

-y[level\ 

be more verbose. A verbosity level (default 1) can follow the -v flag, as in -v3 for even 
more output. This is useful if articles aren't being expired and you want to know why. 

— e days 

give the number of days to use for a default expiration date. If not given, an installation 
dependent default (often 2 weeks) is used. Note that you must use a space between -e 
and days. 

-I 

-I ignore any expiration date explicitly given on articles. This can be used when disk space 

is really tight. -I always ignores expiration dates, while -I only ignores the date if ignor- 
ing it would expire the article sooner. WARNING: If you have articles archived, by giv- 
ing them expiration dates far into the future, these options might remove these files any- 
way. 

— r rebuild the history file without removing any files. In the process, expire formats the 

dbm{Z) format files associated with the history file. 

-h expire articles without using the history file. Both the -r and -h flags use the active file 
for newsgroup information rather than the history file. 

SEE ALSO 

checknews(l), inews(l), readnews(l), recnews(8), sendnews(8), uurec(8) 
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NAME 

fastboot, fasthalt - reboot/halt the system without checking the disks 

SYNOPSIS 

/ete/fastboot [ boot-options ] 
/ete/fasthalt [ halt- options ] 

DESCRIPTION 

Fastboot and fasthalt are shell scripts which reboot and halt the system without checking the file 
systems. This is done by creating a file /fastboot, then invoking the reboot program. The system 
startup script, /etc/ re, looks for this file and, if present, skips the normal invocation of fsck{S). 

SEE ALSO 

halt(8). reboot(8). fc(8) 
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NAME 

fsck - file system consistency check and interactive repair 

SYNOPSIS 

/etc/fsck -p I filesystem ... ] 

/etc/fsck [ -b block# | ( -y J | -n ] ( filesystem | ... 

DESCRIPTION 

The first form of fsck preens a standard set of filesystems or the specified file systems. It is nor- 
mally used in the script /etc/rc during automatic reboot. In this case fack reads the table 
/etc/fstab to determine which file systems to check. It uses the information there to inspect 
groups of disks in parallel taking maximum advantage of i/o overlap to check the file systems as 
quickly as possible. Normally, the root file system will be checked on pass 1, other "root" ("a" 
partition) file systems on pass 2, other small file systems on separate passes (e.g. the "d" file sys- 
tems on pass 3 and the "e" file systems on pass 4), and finally the large user file systems on the 
last pass, e.g. pass 5. A pass number of in fstab causes a disk to not be checked; similarly parti- 
tions which are not shown as to be mounted *'rw" or "ro" are not checked. 

The system takes care that only a restricted class of innocuous inconsbtencies can happen unless 
hardware or software failures intervene. These are limited to the following: 

Unreferenced inodes 

Link counts in inodes too large 

Missing blocks in the free list 

Blocks in the free list also in files 

Counts in the super-block wrong 

These are the only inconsistencies which fsck with the -p option will correct; if it encounters 
other inconsistencies, it exits with an abnormal return status and an automatic reboot will then 
fail. For each corrected inconsistency one or more lines will be printed identifying the file system 
on which the correction will take place, and the nature of the correction. After successfully 
correcting a file system, fsck will print the number of files on that file system and the number of 
used and free blocks. 

Without the -p option, fsck audits and interactively repairs inconsistent conditions for file sys- 
tems. If the file system is inconsistent the operator is prompted for concurrence before each 
correction is attempted. It should be noted that a number of the corrective actions which are not 
fixable under the -p option will result in some loss of data. The amount and severity of data lost 
may be determined from the diagnostic output. The default action for each consistency correc- 
tion is to wait for the operator to respond yes or no. If the operator does not have write permis- 
sion /9cib will default to a -n action. 

Fsck has more consistency checks than its predecessors check, dcheck, fcheck, and icheck com- 
bined. 

The following flags are interpreted by fsck. 

—h Use the block specified immediately after the flag as the super block for the file system. 
Block 32 is always an alternate super block. 

— y Assume a yes response to all questions asked by fsck; this should be used with great cau- 
tion as this is a free license to continue after essentially unlimited trouble has been encoun- 
tered. 

-n Assume a no response to all questions asked by fsck; do not open the file system tat writ- 
ing. 

If no filesystems are given to /9cii; then a default list of file systems is read from the file 
/etc/fbtab. 
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Inconsistencies checked are as follows: 

1. Blocks claimed by more than one inode or the free list. 

2. Blocks claimed by an inode or the free list outside the range of the file system. 

3. Incorrect link counts. 

4. Size checks: 

Directory size not of proper format. 

5. Bad inode format. 

6. Blocks not accounted for anywhere. 

7. Directory checks: 

File pointing to unallocated inode. 
Inode number out of range. 

8. Super Block checks: 

More blocks for inodes than there are in the file system. 

9. Bad free block list format. 

10. Total free block and/or free inode count incorrect. 

Orphaned files and directories (allocated but unreferenced) are, with the operator's concurrence, 
reconnected by placing them in the lost+found directory. The name assigned is the inode 
number. The only restriction is that the directory lost+found must preexist in the root of the 
filesystem being checked and must have empty slots in which entries can be made. This is 
accomplished by making lost+found, copying a number of files to the directory, and then 
removing them (before fsck is executed). 

Checking the raw device is almost always faster. 



FILF.^ 



/etc/fstab contains default list of file systems to check. 

DIAGNOSTICS 

The diagnostics produced by fsck are intended to be self-explanatory. 

SEE ALSO 

f8tab(5), fs(5), newfs(8), mkfs(8), crash(8S), reboot(8) 

BUGS 

Inode numbers for . and .. in each directory should be checked for validity. 

There should be some way to start a fsck -p at pass n. 
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NAME 

ftpd - DARPA Internet File Transfer Protocol server 

SYNOPSIS 

/usr/etc/in.ftpd host.socket 

DESCRIPTION 

Ftpd is the DARPA Internet File Transfer Prototocol server process. The server is invoked by 
the Internet daemon inetd{SC) each time a connection to the ftp service (see 8ervice8{b)) is made, 
with the connection available as descriptor and the host and socket the connection originated 
from (in hex and decimal respectively) as argument. 

Inactive connections are timed out after 60 seconds. 

The ftp server currently supports the following ftp requests; case is not distinguished. 

Request Description 

ACCT specify account (ignored) 

ALLO allocate storage (vacuously) 

APPE append to a file 

CWD change working directory 

DELE delete a file 

HELP give help information 

LIST give list files in a directory ("Is -Ig") 

MODE specify data transfer mode 

NLST give name list of files in directory ("Is") 

NOOP do nothing 

PASS specify password 

PORT specify data connection port 

QUIT terminate session 

RETR retrieve a file 

RNFR specify rename-from file name 

RNTO specify rename-to file name 

STOR store a file 

STRU specify data transfer structure 

TYPE specify data transfer type 

USER specify user name 

XCUP change to parent of current working directory 

XCWD change working directory 

XMKD make a directory 

XPWD print the current working directory 

XRMD remove a directory 

The remaining ftp requests specified in Internet RFC 765 are recognized, but not implemented. 

Ftpd interprets file names according to the "globbing" conventions used by C8h{l). This allows 
users to utilize the metacharacters "*?[]{}"". 

Ftpd authenticates users according to three rules. 

1) The user name must be in the password data base, fetc/paaawd, and not have a null pass- 
word. In this case a password must be provided by the client before any file operations 
may be performed. 

2) The user name must not appear in the file /etc/ftpusera. 

3) If the user name is "anonymous" or "ftp", an anonymous ftp account must be present in 
the password file (user "ftp"). In this case the user is allowed to log in by specifying any 
password (by convention this is given as the client host's name). 
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In the last case, ftpd takes special measures to restrict the client's access privileges. The server 
performs a chroot{2) command to the home directory of the "ftp" user. In order that system 
security is not breached, it is recommended that the "ftp" subtree be constructed with care; the 
following rules are recommended. 

"ftp) Make the home directory owned by "ftp" and unwritable by anyone. 

"ftp/bin) 

Make this directory owned by the super>user and unwritable by anyone. The program 
/«(!) must be present to support the list commands. This program should have mode 111. 

-ftp/etc) 

Make this directory owned by the super-user and unwritable by anyone. The files 
pa88wd{h) and group{h) must be present for the Is command to work properly. These files 
should be mode 444. 

~ftp/pub) 

Make this directory mode 777 and owned by "ftp". Users should then place files which 
are to be accessible via the anonymous account in this directory. 

SEE ALSq 

ftp(lC), 

BUGS 

There is no support for aborting commands. 

The anonymous account is inherently dangerous and should avoided when possible. 

The server must run as the super-user to create sockets with privileged port numbers. It main- 
tains an effective user id of the logged in user, reverting to the super-user only when binding 
addresses to sockets. The possible security holes have been extensively scrutinized, but are possi- 
bly incomplete. 
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NAME 

gettable - get NIC format host tables from a host 

SYNOPSIS 

/ete/gettable host 

DESCRIPTION 

Gettable is a simple program used to obtain the NIC standard host tables from a "nicname" 
server. The indicated host is queried for the tables. The tables, if retrieved, are placed in the file 

h08t8.txt. 

Gettable operates by opening a TCP connection to the port indicated in the service specification 
for "nicname". A request is then made for "ALL" names and the resultant information is placed 
in the output file. 

Gettable b best used in conjunction with the htable{8) program which converts the NIC standard 
file format to that used by the network library lookup routines. 

SEE ALSO 

intro(3N), htable(8) 

BUGS 

Should allow requests for only part of the database. 
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NAME 

getty - set terminal mode 

SYNOPSIS 

/ete/getty ( char J 

DESCRIPTION 

Getty is invoked by init{S) immediately after a terminal is opened, following the making of a con- 
nection. While reading the name getty attempts to adapt the system to the speed and type of ter- 
minal being used. 

Init calls getty with an argument specified by the ttye file entry for the terminal line. Arguments 
other than '0' can be used to make getty treat the line specially. Refer to tty8{5) and gettytab(5) 
for descriptions of how getty uses the data in gettytab to set up the terminal. Normally, it sets the 
speed of the interface to 300 baud, specifies that raw mode is to be used (break on every charac- 
ter), that echo is to be suppressed, and either parity allowed. It types a banner identifying the 
system (from gethostname(2)) and the 'login:' message. Then the user's name is read, a character 
at a time. If a null character is received, it is assumed to be the result of the user pushing the 
'break' ('interrupt') key. The speed is then changed to 1200 baud and the 'login:' is typed again; 
a second 'break' changes the speed to 150 baud and the 'login:' is typed again. Successive 'break' 
characters cycle through the speeds 300, 1200, and 150 baud. 

The user's name is terminated by a new-line or carriage-return character. The latter results in 
the system being set to treat carriage returns appropriately (see tty(4)). 

The user's name is scanned to see if it contains any lower-case alphabetic characters; if not, and if 
the name is nonempty, the system is told to map any future upper-case characters into the 
corresponding lower-case characters. 

Finally, login is called with the user's name as argument. 

SEE ALSO 

init(8), login(l), ioctl(2), tty(4), ttys(5), getty tab(5) 
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NAME 

gxtest - stand alone test for the Sun video graphics board 

SYNOPSIS 

b /■tand/gxtest 

DESCRIPTON 

Gxtest runs stand alone, not under control of the UNIX operating system. With the PROM 
resident monitor in control of the system, type the command: 

> b /stand/gxtest 

and the monitor boots the video test program into memory. Gxteet is completely self-explanatory 
and runs under its own steam. It reports any errors it finds on the screen. 
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NAME 

halt - stop the processor 

SYNOPSIS 

/etc/halt ( -n J I -<i 1 ( -y ) 

DESCRIPTION 

Halt writes out sandbagged information to the disks and then stops the processor. 

OPTIONS 

— n Prevents the sync before stopping. 

— q Do a quick halt, no graceful shutdown is attempted. 

-y Needed if you are trying to halt the system from a dialup. 

SEE ALSO 

reboot(8), shutdown(8) 
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NAME 

htable - convert NIC standard format host tables 

SYNOPSIS 

/usr/etc/htabie file 

DESCRIPTION 

Htable is used to convert host files in the format specified in Internet RFC 810 to the format used 
by the network library routines. Three files are created as a result of running htable: hosts, net- 
works, and gateways. The hosts file is used by the gethostent{ZN) routines in mapping host names 
to addresses. The networks file is used by the getnetent{SN) routines in ma4)ping network names 
to numbers. The gateways file is used by the routing daemon in identifying "passive" Internet 
gateways; see routed{SC) for an explanation. 

If any of the files loealhosts, tocalnetworks, or localgateways are present in the current directory, 
the file's contents is prepended to the output file without interpretation. This allows sites to 
maintain local aliases and entries which are not normally present in the master database. 

Htable is best used in conjunction with the gettable{SC) program which retrieves the NIC database 
from a host. 

SEE ALSO 

intro(3N), gettable(8C) 

BUGS 

Does not properly calculate the gateways file. 
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NAME 

icheck - file system storage consbtency check 

SYNOPSIS 

/usr/etc/icheck ( -• j [ -b numbers J ( filesystem ) 

DESCRIPTION 

N.B.S Icheck is obsoleted for normal consistency checking by f8ck{8). 

Icheck examines a file system, builds a bit map of used blocks, and compares this bit map against 
the free list maintained on the file system. If the file system is not specified, a set of default file 
systems is checked. The normal output of icheck includes a report of 

The total number of files and the numbers of regular, directory, block special and charac- 
ter special files. 

The total number of blocks in use and the numbers of single-, double-, and triple-indirect 
blocks and directory blocks. 

The number of free blocks. 

The number of blocks missing; i.e. not in any file nor in the free list. 

The -B option causes icheck to ignore the actual free list and reconstruct a new one by rewriting 
the super-block of the file system. The file system should be dismounted while this is done; if this 
is not possible (for example if the root file system has to be salvaged) care should be taken that 
the system is quiescent and that it is rebooted immediately afterwards so that the old, bad in-core 
copy of the super-block will not continue to be used. Notice also that the words in the super- 
block which indicate the size of the free list and of the i-list are believed. If the super-block has 
been curdled these words will have to be patched. The —b option causes the normal output 
reports to be suppressed. 

Following the -b option is a list of block numbers; whenever any of the named blocks turns up in 
a file, a diagnostic is produced. 

Icheck is faster if the raw version of the special file is used, since it reads the i-list many blocks at 
a time. 

FILES 

Default file systems vary with installation. 

SEE ALSO 

fsck(8), dcheck(8), ncheck(8), fs(5), clri(8) 

DIAGNOSTICS 

For duplicate blocks and bad blocks (which lie outside the file system) icheck announces the 
difficulty, the i-number, and the kind of block involved. If a read error is encountered, the block 
number of the bad block is printed and icheck considers it to contain 0. 'Bad freeblock' means 
that a block number outside the available space was encountered in the free list, 'n dups in free' 
means that n blocks were found in the free list which duplicate blocks either in some file or in the 
earlier part of the free list. 



BUGS 



Since icheck is inherently two-pass in nature, extraneous diagnostics may be produced if applied 
to active file systems. 

It believes even preposterous super-blocks and consequently can get core images. 

The system should be fixed so that the reboot after fixing the root file system is not necessary. 



Sun Release 1.1 Last change: 4 February 1983 39 



IFCONFIG ( 8C ) MAINTENANCE COMMANDS IFCONFIG ( 8C ) 



NAME 

ifconfig - configure network interface parameters 

SYOPNSIS 

/ete/ifconflg interface [ Ethernet_addre88 ] [ hostname ] [ parameters \ 

DESCRIPTION 

Ifconfig is used to assign an address to a network interface and/or to configure network interface 
parameters. Ifconfig must be used at boot time to define the network address of each interface 
present on a machine; it may ako be used at a later time to redefine an interface's address. Used 
without options, ifconfig displays the current configuration for a network interface. Only the 
super-user may modify the configuration of a network interface. 

The interface parameter is a string of the form "name unit", for example "ieO". 

OPTIONS 

Ethernet_addre88 is the hardware Ethernet address of a given machine. The address is a 6-byte 
hexadecimal value; each byte of the address is separated by a colon. A typical Ethernet adddress 
is '8:0:20:1:1:A3'. This address is contained in the ID PROM on the Sun-2 CPU Board, and is 
reported at boot time as one of the PROM monitor's sign-on messages. The Ethernet^address 
option is normally not used — the hardware supplies the default; the option is used only when 
trying to talk to a device which does not support ARP (like a VAX on a 4.1c network). 

hostname may be either the hostname of a given machine (present in the hostname database, 
ho8t8{b)), or the complete Internet address consisting of your system's network number and the 
machine's unique host number. A typical Internet address might be "192.9.200.44", where 
"192.9.200" is the network number and "44" is the machine's hostnumber. To find a machine's 
Internet address, consult the local /etc/ hosts file. 

The following parameters may be set with ifconfig: 

up Mark an interface "up". 

down Mark an interface "down". When an interface is marked "down", the ^stem 

will not attempt to transmit messages through that interface. 

tradlers Enable the use of a "trailer" link level encapsulation when sending (default). If 

a network interface supports trailers, the system will, when possible, encapsulate 
outgoing messages in a manner which minimizes the number of memory to 
memory copy operations performed by the receiver. 

-trailers Disable the use of a "trailer" link level enc^sulation. 

arp Enable the use of the Address Resolution Protocol in mapping between network 

level addresses and link level addresses (default). Thb is currently implemented 
for mapping between DARPA Internet addreses and lOMb/s Ethernet addresses. 

-arp Disable the use of the Address Resolution Protocol. 

DIAGNOSTICS 

Messages indicating the specified interface does not exit, the requested address is unknown, the 
user is not privileged and tried to alter an interface's configuration. 

SEE ALSO 

rc(8), intro(4N), netstat(l) 
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NAME 

imemtest - stand alone memory test 

SYNOPSIS 

b /stand/imemtest 

DESCRIPTON 

Imemtest runs stand alone, not under control of the UNIX operating system. With the PROM 
resident monitor in control of the system, type the command: 

> b /stand/imemtest 

and the monitor boots the memory test program into memory. Imemtest is completely self- 
explanatory. It prompts for all start and end addresses, and after that it runs under its own 
steam. It reports any errors it finds on the screen. 
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NAME 

inetd - internet services daemon 

SYNOPSIS 

/etc/lnetd [ -d | 

DESCRIPTION 

Inetd is the internet super-server which invokes all internet server processes as needed. 
Connection-oriented services are invoked each time a connection is made, by creating a process. 
This process is passed the connection as file descriptor and an argument of the form 
"sourcehost.sourceport" where sourcehost is hex and sourceport is decimal. 

Datagram oriented services are invoked when a datagram arrives; a process is created and passed 
the connection as file descriptor 0. Inetd will look at the socket where datagrams arrive again 
only after this process completes. The paradigms for such proceses are either to read off the 
incoming datagram and then fork and exit, or to process the arriving datagram and then time 
out. 

Inetd consults eerv€re{S) when it is invoked, and supports whatever services are in that file. 

OPTIONS 

— d Specifies that debugging traces are to be turned on for connection-oriented (TCP) ser- 

vices. 

FILES 

/etc/servers list of internet server processes 

SEE ALSO 

servers(5), comsat(8C), ftpd(8C), rexecd(8C), rlogind(8C), syslog(8), rshd(8C), talkd(8C), 
telnetd(8C), tftpd(8C) 

BUGS 

There is no provision for selectively invoking TCP debugging packet tracing per-service. 

Should reread the servers(5) file on receipt of a SIGHUP signal. 
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NAME 

init - process control initialization 

SYNOPSIS 

/etc/init 

DESCRIPTION 

Init is invoked inside UNDC as the last step in the boot procedure. It normally then runs the 
automatic reboot sequence as described in reboot{8), and if this succeeds, begins multi-user opera- 
tion. If the reboot fails, it commences single user operation by giving the super-user a shell on the 
console. It is possible to pass parameters from the boot program to init so that single user opera- 
tion is commenced immediately. When such single user operation is terminated by killing the 
single-user shell (i.e. by hitting *D), init runs /etc/rc without the reboot parameter. This com- 
mand file performs housekeeping operations such as removing temporary files, mounting file sys- 
tems, and starting daemons. 

In multi-user operation, init's role is to create a process for each terminal port on which a user 
may log in. To begin such operations, it reads the file /etc/ttys and forks several times to create 
a process for each terminal specified in the file. Each of these processes opens the appropriate ter- 
minal for reading and writing. These channels thus receive file descriptors 0, 1 and 2, the stan- 
dard input and output and the diagnostic output. Opening the terminal will usually involve a 
delay, since the open is not completed until someone is dialed up and carrier established on the 
channel. If a terminal exists but an error occurs when trying to open the terminal init complains 
by writing a message to the system console; the message is repeated every 10 minutes for each 
such terminal until the terminal is shut off in /etc/ttys and init notified (by a hangup, as 
described below), or the terminal becomes accessible (init checks again every minute). After an 
open succeeds, /etc/getty is called with argument as specified by the second character of the ttya 
file line. Getty reads the user's name and invokes login to log in the user and execute the Shell. 

Ultimately the Shell will terminate because of an end-of-file either typed explicitly or generated as 
a result of hanging up. The main path of init, which has been waiting for such an event, wakes 
up and removes the appropriate entry from the file utmp, which records current users, and makes 
an entry in /u8r/adm/wtmp, which maintains a history of logins and logouts. The wtmp entry is 
made only if a user logged in successfully on the line. Then the appropriate terminal is reopened 
and getty is reinvoked. 

Init catches the hangup signal (signal SIGHUP) and interprets it to mean that the file /etc/ ttya 
should be read again. The Shell process on each line which used to be active in ttyg but is no 
longer there is terminated; a new process is created for each added line; lines unchanged in the file 
are undisturbed. Thus it is possible to drop or add phone lines without rebooting the system by 
changing the ttys file and sending a hangup signal to the init process: use 'kill -HUP 1.' 

Init will terminate multi-user operations and resume single-user mode if sent a terminate (TERM) 
signal, i.e. "kill -TERM 1". If there are processes outstanding which are deadlocked (due to 
hardware or software failure), init will not wait for them all to die (which might take forever), but 
will time out after 30 seconds and print a warning message. 

Init will cease creating new getty's and allow the system to slowly die away, if it is sent a terminal 
stop (TSTP) signal, i.e. "kill -TSTP 1". A later hangup will resume full multi-user operations, or 
a terminate will initiate a single user shell. This hook is used by reboot{8) and halt{S). 

Init'a role is so critical that if it dies, the system will reboot itself automatically. If, at bootstrap 
time, the init process cannot be located, the system will loop in user mode at location 0x13. 

DIAGNOSTICS 

initt ttyx cannot open. A terminal which is turned on in the re file cannot be opened, likely 
because the requisite lines are either not configured into the system or the associated device was 
not attached during boot-time ^stem configuration. 
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WARNING: Something is hung (wont die); ps axl advised. A process is hung and could 
not be killed when the system was shutting down. This is usually caused by a process which is 
stuck in a device driver due to a persistent device error condition. 

FILES 

/dev /console, /dev/tty*, /etc/utmp, /usr/adm/wtmp, /etc/ttys, /etc/rc 

SEE ALSO 

login(l), kill(l), sh(l), ttys(5), getty(8), rc(8), reboot(8), halt(8), shutdown(8) 
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NAME 

iostat - report I/O statistics 

SYNOPSIS 

ioitat [ interval [ count ] ] 

DESCRIPTION 

Iostat iteratively reports the number of characters read and written to terminals, and, for each 
df^k, the number of seeks and transfers per second, and the milliseconds per average seek. It also 
gi]{fes the percentage of time the ^stem has spent in user mode, in user mode running low priority 
(qlped) processes, in system mode, and idling. 

Tuln compute this information, for each disk, seeks and data transfer completions and number of 
yfi^^fds transferred are counted; for terminals collectively, the number of input and output charac- 
ters are counted. Also, each sixtieth of a second, the state of each disk is examined and a tally is 
made if the disk is active. From these numbers and given the transfer rates of the devices it is 
possible to determine average seek times for each device. 

The optional interval argument causes iostat to report once each interval seconds. The first report 
is for all time since a reboot and each subsequent report is for the last interval only. 

The optional count argument restricts the number of reports. 

FILES 

/dev/kmem 
/vmunix 

SEE ALSO 

vmstat(8) 
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NAME 

kgmon - generate a dump of the operating system's profile buffers 

SYNOPSIS 

/usr/etc/kgmon { -b ] [ -h ) ( -r ) ( -p J | system ] ( memory ] 

DESCRIPTION 

Kgmon is a tool used when profiling the operating system. When no arguments are supplied, 
kgmon indicates the state of operating system profiling as running, off, or not configured (see 
config{S)). If the -p flag is specified, kgmon extracts profile data from the operating system and 
produces a gmon.out file suitable for later analysb by gproJ{l). 

OPTIONS 

-1^ Resume the collection of profile data. 

— 1| Stop the collection of profile data. 

— p Dump the contents of the profile buffers into a gmon.out file. 

— r Reset all the profile buffers. If the -p flag is also specified, the gmon.out file is generated 

before the buffers are reset. 

If neither -b nor -h is specified, the state of profiling collection remains unchanged. For exam- 
ple, if the -p flag is specified and profile data is being collected, profiling is momentarily 
suspended, the operating system profile buffers are dumped, and profiling is immediately resumed. 

FILES 

/vmunix - the default system 
/dev/kmem - the default memory 

SEE ALSO 

gprof (1), config(8) 

DIAGNOSTICS 

Users with only read permission on /dev/kmem cannot change the state of profiling collection. 
They can get a gmon.out file with the warning that the data may be inconsistent if profiling is in 
progress. 
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NAME 

Ipc - line printer control program 

SYNOPSIS 

/usr/etc/lpc [ commiand [ argument ... ] ] 

DESCRIPTION 

Lpc is used by the system administrator to control the operation of the line printer system. For 
each line printer configured in /etc/printcap, lpc may be used to: 

• disable or enable a printer, 

• disable or enable a printer's spooling queue, 

• rearrange the order of jobs in a spooling queue, 

• find the status of printers, and their associated spooling queues and printer dameons. 

Without any arguments, lpc will prompt for commands from the standard input. If arguments are 
supplied, lpc interprets the first argument as a command and the remaining arguments as parame- 
iefifi to the command. The standard input may be redirected so that lpc reads commands from a 
fill, Commands may be abreviated; the following is the list of recognized commands. 

? I conmiand ... ] 

QiJlD ( command ... ] 

Print a short description of each command specified in the argument list, or, if no argu- 
ments are given, a list of the recognized commands. 

abort { all | printer ... } 

Terminate an active spooling daemon on the local host immediately and then disable 
printing (preventing new daemons from being started by Ipr) for the specified printers. 

clean { all \ printer ... } 

Remove all files beginning with "cf", "tf", or "df" from the specified printer queue(s) on 
the local machine. 

enable { all | printer ... } 

Enable spooling on the local queue for the listed printers. This will allow Ipr to put new 
jobs in the spool queue. 

ex|t 

qujt 

Exit from lpc. 

disable { all | printer ... } 

Turn the specified printer queues off. This prevents new printer jobs from being entered 
into the queue by Ipr. 

restart { all | printer ... } 

Attempt to start a new printer daemon. This is useful when some abnormal condition 
causes the daemon to die unexpectedly leaving jobs in the queue. Lpq will report that 
there is no daemon present when this condition occurs. 

start { all | printer ... } 

Enable printing and start a spooling daemon for the listed printers. 

status { all ] [ printer ... ] 

Display the status of daemons and queues on the local machine. 

stQB { all I printer ... } 

Stop a spooling daemon after the current job completes and disable printing. 
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FILES 

/etc/printcap printer description file 

/usr/spool/* spool directories 

/usr/spool/*/lock lock file for queue control 

SEE ALSO 

lpd(8), Ipr(l), Ipq(l), Iprm(l), printcap(5) 

DIAGNOSTICS 

?Ambiguous command abreviation matches more than one command 

?Invalid command no match was found 

?PriviIeged command command can be executed by root only 
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NAME 

Ipd - line printer daemon 

SYNOPSIS 

/usr/Ub/lpd I -1 1 I -L logfile | [ port # | 

DESCRIPTION 

Lpd is the line printer daemon (spool area handler) and is normally invoked at boot time from the 
rc(8) file. It makes a single pass through the print cap {5) file to find out about the existing 
printers and prints any files left after a crash. It then uses the system calls li8ten{2) and accept{2) 
to receive requests to print files in the queue, transfer files to the spooling area, display the queue, 
or remove jobs from the queue. In each case, it forks a child to handle the request so the parent 
can continue to listen for more requests. The Internet port number used to rendezvous with other 
processes is normally obtained with get8ervent{ZN) but can be changed with the portifi argument. 
The -L option changes the file used for writing error conditions from the system console to logjUe. 
The —1 flag causes lpd to log valid requests received from the network. This can be useful for 
debugging purposes. 

Access control is provided by two means. First, all requests must come from one of the machines 
listed in the file fetc/hoeta.equiv. Second, if the "rs" capability is specified in the printcap entry 
for the printer being accessed, Ipr requests will only be honored for those users with accounts on 
the machine with the printer. 

The file lock in each spool directory is used to prevent multiple daemons from becoming active 
simultaneously, and to store information about the daemon process for lpr{l), lpq{l), and /prm(l). 
After the daemon has successfully set the lock, it scans the directory for files beginning with cf. 
Lines in each c/file specify files to be printed or non-printing actions to be performed. Each such 
line begins with a key character to specify what to do with the remainder of the line. 

J Job Name. String to be used for the job name on the burst page. 

C Classification. String to be used for the classification line on the burst page. 

L Literal. The line contains identification info from the password file and causes the banner 

page to be printed. 

T Title. String to be used as the title for pr(l). 

H Host Name. Name of the machine where Ipr was invoked. 

P Person. Login name of the person who invoked Ipr. This is used to verify ownership by 

Iprm. 

M Send mail to the specified user when the current print job completes. 

f Formatted File. Name of a file to print which is already formatted. 

I Like "f" but passes control characters and does not make page breaks. 

p Name of a file to print using pr(l) as a filter. 

t Troff File. The file contains troff{l) output (C/A/T phototypesetter commands). 

d DVI File. The file contains TeX output (DVI format from Stanford). 

g Graph File. The file contains data produced by plot(SX). 

c Cifplot File. The file contains data produced by cifplot. 

v The file contains a raster image. 

r The file contains text data with FORTRAN carriage control characters. 

1 Troff Font R. Name of the font file to use instead of the default. 

2 Troff Font I. Name of the font file to use instead of the default. 

3 Troff Font B. Name of the font file to use instead of the default. 
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4 Troff Font S. Name of the font file to use instead of the default. 

W Width. Changes the page width (in characters) used by pr(l) and the text filters. 

I Indent. The number of characters to indent the output by (in ascii). 

U Unlink. Name of file to remove upon completion of printing. 

N File name. The name of the file which is being printed, or a blank for the standard input 

(when Ipr is invoked in a pipeline). 

If a file can not be opened, a message will be placed in the log file (normally the console). Lpd 
will try up to 20 times to reopen a file it expects to be there, after which it will skip the file to be 
printed. 

Lpd uses flock{2) to provide exclusive access to the lock file and to prevent multiple deamons from 
becoming active simultaneously. If the daemon should be killed or die unexpectedly, the lock file 
need not be removed. The lock file is kept in a readable ASCII form and contains two lines. The 
first is the process id of the daemon and the second is the control file name of the current job 
being printed. The second line is updated to refiect the current status of lpd for the programs 
lpq{l) and /prm(l). 



FILES 



/etc/printcap printer description file 

/usr/spool/* spool directories 

/dev/lp* line printer devices 

/etc/hosts.equiv lists machine names allowed printer access 

SEE ALSO 

lpc(8), pac(8), Ipr(l), Ipq(l), Iprm(l), printcap(5) 
4.SBSD Line Printer Spooler Manual 
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NAME 

MAKEDEV - make system special files 

SYNOPSIS 

/dev/MAKEDEV device... 

DESCRIPTION 

MAKEDEV is a shell script normally used to install special files. It resides in the /(/et; directory, 
as this is the normal location of special files. Arguments to MAKEDEV are usually of the form 
device-name? where device-name is one of the supported devices listed in section 4 of the manual 
and '?' is a logical unit number (0-9). A few special arguments create assorted collections of dev- 
ices and are listed below. 

std Create the standard devices for the system; for example, /dev/console, /dev/tty. 

local Create those devices specific to the local site. This request runs the shell file 
I devj MAKEDEVAocal. Site specific commands, such as those used to setup dialup lines 
as 'ttyd?' should be included in this file. 

Since all devices are created using mknod{^), this shell script is useful only to the super-user. 

DIAGNOSTICS 

Either self-explanatory, or generated by one of the programs called from the script. Use sh - 
X MAKEDEV in case of trouble. 

SEE ALSO 

intro(4), config(8), mknod(8) 
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NAME 

makekey - generate encryption key 

SYNOPSIS 

/usr /Ub/ makek^ 

DESCRIPTION 

Makekey improves the usefulness of encryption schemes depending on a key by increasing the 
amount of time required to search the key space. It reads 10 bytes from its standard input, and 
writes 13 bytes on its standard output. The output depends on the input in a way intended to be 
difficult to compute (that is, to require a substantial fraction of a second). 

The first eight input bytes (the input key) can be arbitrary ASCII characters. The last two (the 
salt) are best chosen from the set of digits, upper- and lower-case letters, and '.' and '/'• I'he salt 
characters are repeated as the first two characters of the output. The remaining 11 output char- 
acters are chosen from the same set as the salt and constitute the output key. 

The transformation performed b essentially the following: the salt is used to select one of 4096 
cryptographic machines all based on the National Bureau of Standards DES algorithm, but 
modified in 4096 different ways. Using the input key as key, a constant string is fed into the 
machine and recirculated a number of times. The 64 bits that come out are distributed into the 
66 useful key bits in the result. 

Makekey is intended for programs that perform encryption (for instance, ed and crypt(l)). Usually 
makekey 's input and output will be pipes. 

SEE ALSO 

crypt(l), ed(l) . 
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NAME 

mkfs - construct a file system 

SYNOPSIS 

/etc/mkfs special sixe [ nsect ] [ ntrack ] [ blksize ] [ fragsize ] [ ncpg ] [ minfree ] [ rps ] 

DESCRIPTION 

N.B.: file system are normally created with the newf8{S) command. 

Mkfa constructs a file system by writing on the special file special. The numeric size specifies the 
number of sectors in the file system. Mkfa builds a file system with a root directory and a 
het-h found directory (see f8ck{8)). The number of i-nodes is calculated as a function of the file 
system size. No boot program is initialized by mkfs (see newf8{S)). 

OPTIONS 

The optional arguments allow fine tune control over the parameters of the file system. 

Nsect specify the number of sectors per track on the disk. 

Ntrack 

specify the number of tracks per cylinder on the disk. 

Blksise 

gives the primary block size for files on the file system. It must be a power of two, 
currently selected from 4096 or 8192. 

Fragslie 

gives the fragment size for files on the file system. The fragslse represents the smallest 
amount of disk space that will be allocated to a file. It must be a power of two currently 
selected from the range 512 to 8192. 

Ncpg specifies the number of disk cylinders per cylinder group. This number must be in the 
range 1 to 32. 

Minfree 

specifies the minimum percentage of free disk space allowed. Once the file system capar 
city reaches this threshold, only the super-user is allowed to allocate disk blocks. The 
default value is 10%. 

rps If a disk does not revolve at 60 revolutions per second, this parameter may be specified. 

Users with special demands for their file systems are referred to the paper cited below for a dis- 
cussion of the tradeoffs in using different configurations. 

SEE ALSO 

fs(5), dir(5), fsck(8), newfs(8), tunefs(8) 

McKusick, Joy, Leffler; A Fast File System for Unix, Computer Systems Research Group, Dept of 
EECS, Berkeley, CA 94720; 
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NAME 

mknod - build special file 

SYNOPSIS 

/etc/ mknod name [ c ] [ b ] major minor 

DESCRIPTION 

Mknod makes a special file. The first argument is the name of the entry. The second is b if the 
special file is block-type (disks, tape) or c if it is character-type (other devices). The last two 
arguments are numbers specifying the major device type and the minor device (for example, unit, 
drive, or line number). 

Mknod is only for use by system configuration people. Normally you should use fdev/MAKEDEV 
instead when making special files. 

SEE ALSO 

mknod(2), makedev(8) 
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NAME 

mkproto - construct a prototype file system 

SYNOPSIS 

/usr/etc/mkproto special proto 

DESCRIPTION 

Mkproto is used to bootstrap a new file system. First a new file system is created using newf8{S). 
Mkproto is then used to copy files from the old file ^stem into the new file system according to 
the directions found in the prototype file proto. The prototype file contains tokens separated by 
spaces or new lines. The first tokens comprise the specification for the root directory. File 
specifications consbt of tokens giving the mode, the user-id, the group id, and the initial contents 
of the file. The syntax of the contents field depends on the mode. 

The mode token for a file is a 6 character string. The first character specifies the type of the file. 
(The characters -bed specify regular, block special, character special and directory files respec- 
tively.) The second character of the type is either u or — to specify set-user-id mode or not. The 
third is g or - for the set-group-id mode. The rest of the mode is a three digit octal number giv- 
ing the owner, group, and other read, write, execute permissions, see chmod(l). 

Two decimal number tokens come after the mode; they specify the user and group ID's of the 
owner of the file. 

If the file is a regular file, the next token is a pathname whence the contents and size are copied. 

If the file is a olock or character special file, two decimal number tokens follow which give the 
major and minor device numbers. 

If the file is a directory, mkproto makes the entries . and .. and then reads a list of names and 
(recursively) file specifications for the entries in the directory. The scan b terminated with the 
token $. 

A sample prototype specification follows: 

cl— 777 3 1 

usr d~777 3 1 







sh 
ken 


— 755 3 1 /bin/sh 

d— 755 6 1 

$ 

b— 644 3 10 

c— 644 3 10 






bO 
cO 

$ 


1 

SEE ALSO 

f8(5), dir(5), fsck(8), newfs(8) 



BUGS 



There should be some way to specify links. 

There should be some way to specify bad blocks. 

Mkproto can only be run on virgin file systems. It should be possible to copy files into existent 
file systems. 
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NAME 

mount, umount - mount and dismount file system 

SYNOPSIS 

/etc/ mount ( -a | | -f | | -' ] | -v ] | special | [ dir ] 

/etc/umount [ -a ] | -v | | rfev . . . | 

DESCRIPTION 

Mount announces to the system that a removable file system is present on the device special. The 
file dir must exist already and it must be a directory (unless the root of the mounted file system is 
not a directory). It becomes the name of the newly mounted root. The optional argument -r 
indicates that the file system is to be mounted read-only. 

Umount announces to the system that the removable file system previously mounted on device 
«pec»a( should be removed. 

Mount and umount maintain a table of mounted devices in fetc/mtab. If invoked without an 
argument, mount displays the table. 

Physically write-protected and magnetic tape file systems must be mounted read-only or errors 
will occur when access times are updated, whether or not any explicit write is attempted. 

MOUNT OPTIONS 

-r Mount the specified file system read-only. 

-a Attempt to mount or unmount all the file systems described in /etc/fstab. In this case, 
special and dir are taken from /etc/fstab. The special file name from /etc/fstab \s the 
block special name. 

-V Verbose — mount displays a message indicating the file system being mounted. 

-f Fake a new /etc/mtab entry. Mount does not actually mount any file systems. 

UMOUNT OPTIONS 

-a Attempt to unmount all the file systems described in /etc/fstab. In this case, special is 
taken from /etc/fstab. 

-V Verbose — umount displays a message indicating the file system being unmounted. 

FILES 

/etc/mtab mount table 

/etc/fstab file system table 

SEE ALSO 

mount(2), mtab(5), fstab(5) 

BUGS 

Mounting file systems full of garbage will crash the system. 

Mounting a root directory on a non-directory makes some apparently good pathnames invalid. 
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NAME 

ncheck - generate names from i-numbers 

SYNOPSIS 

/usr/etc/ncheck ( -1 numbers ) | -a | ( -s ) ( fiieayetem J 

DESCRIPTION 

N.B.: For most normal file system maintenance, the function of ncheck is subsumed by f8ck{8). 

Ncheck with no argument generates a pathname versus i-number Ibt of all files on a set of default 
file systems. Names of directory files are followed by '/•'• 

A file system may be specified by the optional filesystem argument. 

The report is in no useful order, and probably should be sorted. 

OPTIONS 

—I numbers 

Report only those files whose i-numbers follow. 

-a Print the names '.' and '. .', which are ordinarily suppressed. 

-8 Report only special files and files with set-user-ID mode. This is intended to discover 

concealed violations of security policy. 

SEE ALSO 

sort(l), dcheck(8), fsck(8), icheck(8) 

DIAGNOSTICS 

When the filesystem structure is improper, '??' denotes the 'parent' of a parentless file and a path- 
name beginning with *«,»* denotes a loop. 
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NAME 

nd - network disk control 

SYNOPSIS 

/etc/nd I command ] 

DESCRIPTION 

The nd command controls the network disk service of the kernel as described in nd{4p). A single 
command may be given on the command line; if none is given then the standard input is read for 
a list of commands. Typically, the file /etc/nd. local is used for input. Lines beginning with '#' 
are considered to be comments. 

The available commands are: 

user hostname hisunit mydev myoff mysize mylunit 

For the client hostname transform incoming requests for hisunit into server device mydev 
at offset myoff and size mysize sectors, /dey /ndlmytunit provides a local name for this 
disk "subpartition" c If mysize is "-1", then this user unit is equivalent to the entire 
filesystem partition mydev (no "subpartioning" is done.) If mylunit is "-1" then no local 
name is needed for this user unit; this is usually the case with a swap unit, or a unit 
represented by an entire filesystem. If hostname is a numeric zero, hisunit refers to a 
public unit. 

ether hostname ether _addt [ maxpacks ] 

The ether command associates an Ethernet address ether_addr with the client hostname. 
This information is required in order for a client to learn his Internet address when it 
boots — nd provides the Internet address for hostname based on the Ethernet address 
received in a boot request. The Ethernet address is given as siz hex bytes separated by 
colons, e.g., 8:0:20:l:l:a3. At least one previous user command must have been issued 
for the client. The maxpacks option may be given to set the maximum number of pack- 
ets that the server will send to the client before requesting an acknowledge. The default 
is 6; it should suffice unless the client Ethernet interface is very slow. 

version versionnumber 

The version command gives the level of configuration of the server. Occasionally the 
need arises to reorganize or reload the diskless partitions. Since the clients will rewrite 
locally cached blocks, they must be kept from writing their filesystems until they reboot. 
Before such a reorganization occurs, the system manager should warn diskless users to 
save files and halt their machines. Modification of the partitions should occur with the 
disk server off. After modification is complete, versionnumber should be incremented to 
force users to reboot. 



son 

BOff 

clear 



Starts the network disk server. This command should be issued after all user, ether, 
and version commands. 

Stops the disk server until a subsequent son command. 



Stops the disk server and clears all user and ether information. 

serverat hostname 

Systems with disks may use the serverat command to specify a disk server if they wish 
to user a network disk in addition to their locally attached disk. Even then, this com- 
mand is only necessary if they wish to use a public network disk or if they wish to change 
network disk servers. 
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FILES 

/etc/nd. local 

SEE ALSO 

nd(4p) 

BUGS 

No sanity checking of disk partitions is done. 
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NAME 

netstat - show network status 

SYNOPSIS 

netstat [ -Aahlmnrs ] ( -a ] | interval ] ( system ] ( core ] 

DESCRIPTION 

Netstat symbolically displays the contents of various network-related data structures. 

OPTIONS 

-A show the address of any associated protocol control blocks; used for debugging. 

-a show the state of all sockets; normally sockets used by server processes are not shown 

-h show the state of the IMP host table 

-1 show the state of interfaces which have been auto-configured (interfaces statically 

configured into a system, but not located at boot time are not shown) 

-m show statistics recorded by the memory management routines (the network manages a 
"private share" of memory) 

-n show network addresses as numbers (normally netstat interprets addresses and attempts 
to display them symbolically), proto; 

— ■ show per-protocol statistics 

-r show the routing tables 

The arguments, system and core allow substitutes for the defaults "/vmunix" and "/dev/kmem". 

If an interval is specified, netstat will continuously display the information regarding packet traffic 
on the configured network interfaces, pausing interval seconds before refreshing the screen. 

There are a number of display formats, depending on the information presented. The default 
display, for active sockets, shows the local and remote addresses, send and receive queue sizes (in 
bytes), protocol, and, optionally, the internal state of the protocol. 

Address formats are of the form "host.port" or "network.port" if a socket's address specifies a 
network but no specific host address. When known the host and network addresses are dbplayed 
symbolically according to the data bases /etc/hosts and /etc/ networks, respectively. If a symbolic 
name for an address is unknown, or if the -n option is specified, the address is printed in the 
Internet "dot format"; refer to »net(3N) for more information regarding this format. Unspecified, 
or "wildcard", addresses and ports appear as "*". 

The interface; display provides a table of cumulative statistics regarding packets transferred, 

errors, and collisions. The network address (currently Internet specific) of the interface and the 

maximum transmission unit ("mtu") are also displayed. 

i •' ■'^- i' 

The routing tabte display indicates the available routes and their status. Each route consists of a 

destination host or network and a gateway to use in forwarding packets. The flags field shows the 
state of the route ("U" if "up"), and whether the route is to a gateway ("G"). Direct routes are 
created for each interface attached to the local host. The refcnt field gives the current number of 
active uses of the route. Connection oriented protocols normally hold on to a single route for the 
duration of a connection while connectionless protocols obtain a route then discard it. The use 
field provides a count of the number of packets sent using that route. The interface entry indi- 
cates the network interface utilized for the route. 

When netstat is invoked with an interval argument, it displays a running count of statistics 
related to network interfaces. This display consists of a column summarizing information for all 
interfaces, and a column for the interface with the most tragic since the system was last rebooted. 
The first line of each screen of information contains a summary since the ^stem was last 
rebooted. Subsequent lines of output show values accumulated over the preceding interval. 
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SEE ALSO 

iostat(8), vmstat(8), hosts(5), networks(5), protocoIs(5), services(5), trpt(8C) 

BUGS 

The notion of errors is ill-defined. Collisions mean something else for the IMP. 
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NAME 

newaliases - rebuild the data base for the mail aliases file 

SYNOPSIS 

newaliases 

DESCRIPTION 

Newaliases rebuilds the random access data base for the mail aliases file /usr/ lib/ alias ea. It must 
be run each time /usr/ lib/ aliases is changed in order for the change to take effect. 

SEE ALSO 

aliases(5), sendmail(8) 
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NAME 

newfs - construct a new file system 

SYNOPSIS 

/ete/newfi [ -v ) [ -n | [ mlcfs-options | spedal [ disk-type ] 

DESCRIPTION 

Newfs is a "friendly" front>end to the mA/»(8) program. On the VAX, newfe will look up the type 
of disk a file system is being created on in the disk description file /etc/disktab; on the Sun the 
disk type is determined by reading the disk label. New/a then calculate the appropriate parame- 
ters to use in calling mkfs, then build the file system by forking mkfa and, if the file system is a 
root partition, install the necessary bootstrap programs in the initial 16 sectors of the device. 

OPTIONS 

-n Do not instal the bootstrap programs. 

-V newfs prints out its actions, including the parameters passed to mkfs. 

Options which may be used to override default parameters passed to mkfa are: 

—8 size The size of the file system in sectors. 

-b block-slse 

The block size of the file system in bytes. 

-f frag-flise 

The fragment size of the file system in bytes. 

-t # tracks/cylinder 

-c #cylinder8/group 

The number of cylinders per cylinder group in a file system. The default value used is 
16. 

-m f^ee space % 

The percentage of space reserved from normal users; the minimum free space thresh- 
hold. The default value used is 10%. 

-r revolutions/ minute 

The speed of the disk in revolutions per minute (normally 3600). 

FILES 

/etc/disktab for disk geometry and file partition information (VAX only) 

/etc/mkfs to actually build the file system 

/usr/mdec for boot strapping programs 

SEE ALSO 

fs(5), fsck(8), tunefs(8) 

McKusick, Joy, Leffler; "A Fast File System for Unix", Computer Systems Research Group, Dept 
of EECS, Berkeley, CA 94720; TR #7, September 1982. 
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NAME 

pac - printer /plotter accounting information 

SYNOPSIS 

/uBr/etc/pac | -Pprinter ] [ -pprice 1 ( -• | | -r 1 | -c 1 | name ... ) 

DESCRIPTION 

Pac reads the printer/plotter accounting files, accumulating the number of pages (the usual case) 
or feet (for raster devices) of paper consumed by each user, and printing out how much each user 
consumed in pages or feet and dollars. If any names are specified, then statistics are only printed 
for those users; usually, statistics are printed for every user who has used any paper. 

OPTIONS 

-P printer 

Do accounting for the named printer. Normally, accounting is done for the default 
printer (site dependent) or the value of the PRINTER environment variable is used. 

-pprice 

Use the value price for the cost in dollars instead of the default value of 0.02. 

~c Sorted the output by cost; usually the output is sorted alphabetically by name. 

-r Reverse the sorting order. 

-■ Summarize the accounting information on the summary accounting file; this summary is 

necessary since on a busy system, the accounting file can grow by several lines per day. 

FILES 

/usr/adm/?acct raw accounting files 

/usr/adm/?_sum summary accounting files 

BUGS 

The relationship between the computed price and reality is as yet unknown. 
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NAME 

pstat - print system facts 

SYNOPSIS 

/ete/pstat -alxptufT | suboptions | | system | [ corefile | 

DESCRIPTION 

Pstat interprets the contents of certain system tables. If corefile is given, the tables are sought 
there, otherwise in /dev/kmem. The required namelist is taken from /vmunix unless system is 
specified. 

OPTIONS 

—a Under -p, describe all process slots rather than just active ones. 

-1 Print the inode table with the these headings: 

LOC The core location of this table entry. 
FLAGS Miscellaneous state variables encoded thus: 

L locked 

U update time (/*(5)) must be corrected 

A access time must be corrected 

M file system is mounted here 

W wanted by another process (L flag is on) 

T contains a text file 

C changed time must be corrected 

S shared lock applied 

E exclusive lock applied 

Z someone waiting for an exclusive lock 
CNT Number of open file table entries for this inode. 

DEV Major and minor device number of file system in which this inode resides. 
RDC Reference count of shared locks on the inode. 
WRC Reference count of exclusive locks on the inode (this may be > 1 if, for example, 

a file descriptor is inherited across a fork). 
INO I-number within, the device. 

MODE Mode bits, see chmod{2). 
NLK Number of links to this inode. 
UID User ID of owner 

SIZ/DEV Number of by tea in an ordinary file, or major and minor device of special file. 

-X Prints the text table with these headings: 

LOC The core location of thb table entry. 
FLAGS Miscellaneous state variables encoded thus: 

T ptrace(2) in effect 

W text not yet written on swap device 

L loading in progress 

K locked 

w wanted (L flag is on) 

P resulted from demand-page-from-inode exec format (see execve{2)) 

DADDR Disk address in swap, measured in multiples of 512 bytes. 
CADDR Head of a linked list of loaded processes using this text segment. 
SIZE Size of text segment, measured in multiples of 512 bytes. 
IPTR Core location of corresponding inode. 
CNT Number of processes using this text segment. 
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CCNT Number of processes in core using this text segment. 

— p Print process table for active processes with these headings: 

LOG The core location of this table entry. 
S Run state encoded thus: 

no process 

1 (unused) 

3 runnable 

4 being created 

5 being terminated 

6 stopped under trace 

F Miscellaneous state variables, or-ed together (hexadecimal): 

0000001 loaded 

0000002 a system process (scheduler or page-out daemon) 
0000004 locked for swap out 

0000008 swapped out during process creation 

0000010 traced 

0000020 used in tracing 

0000040 (unused) 

0000080 in page-wait 

0000100 prevented from swapping during forl^2) 

0000200 restore old sigmask after taking signal 

0000400 exiting 

0001000 process resulted from a vfork{2) which is not yet complete 

0002000 another flag for t;/orib(2) 

0004000 process has no virtual memory, as it is a parent in the context of 
vfork{2) 

0008000 process is demand paging data pages from its text inode. 

0010000 process has advised of sequential behavior with vadvi8e(2). 

0020000 process has advised of anomalous behavior with vadvi8e{2). 

0040000 process is in a sleep which will timeout. 

0080000 (unused) 

0100000 using old signal mechanism 

0200000 process is owed a profiling tick. 

0400000 process is setting up a 8elect{2) call 

800000 Process is a login process 

1000000 Page tables for this process have changed (tlb is dirty) 
POIP number of pages currently being pushed out from this process. 
PR! Scheduling priority, see 8etpriority{2). 
SIGNAL Signals received (signals 1-32 coded in bits 0-31), 
UID Real user ID. 

SLP Amount of time process has been blocked. 
TiM Time resident in seconds; times over 127 coded as 127. 
CPIJ Weighted integral of CPU time, for scheduler. 
Nl Nice level, see 8etpriority{2). 

PGRP Process number of root of process group (the opener of the controlling terminal). 
FID The process ID number. 

PPID The process ID of parent process. 
ADDR If in core, the page frame number of the first page of the *u-area' of the process. If 

swat)ped out, the position in the swap area measured in multiples of 512 bytes. 
RSS Resident set size - the number of physical page frames allocated to this process. 
SRSS RSS at last swap (0 if never swapped). 
SIZE Virtual size of process image (data+ stack) in multiples of 512 bytes. 
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WCHAN 

Wait channel number of a waiting process. 

LINK Link pointer in list of runnable processes. 

TEXTP If text is pure, pointer to location of text table entry. 

CLKT Countdown for real interval timer, 8etitiiner{2) measured in clock ticks (10 mil- 
liseconds). 

~t Print table for terminals with these headings: 

RAW Number of characters in raw input queue. 

CAN Number of characters in canonicalized input queue. 

OUT Number of characters in putput queue. 

MODE See tty{4). 

ADDR Physical device address. 

DEL Number of delimiters (newlines) in canonicalized input queue. 

COL Calculated column position of terminal. 

STATE Miscellaneous state variables encoded thus: 

W waiting for open to complete 

O open 

S has special (output) start routine 

C carrier is on 

B busy doing output 

A process is awaiting output 

X open for exclusive use 

H hangup on close 
PGRP Process group for which this is controlling terminal. 
DISC Line discipline; blank is old tty OTTYDISC or "new tty" for NTTYDISC or "net" 

for NETLDISC (see bk{i)). 

-u print information about a user process; the next argument is its address as given by p8{l). 
The process must be in main memory, or the file used can be a core image and the address 
0. 

-f Print the open file table with these headings: 

LOC The core location of this table entry. 

TYPE The type of object the file table entry points to. 

FLG Miscellaneous state variables encoded thus: 

R open for reading 
W open for writing 
A open for appending 

CNT Number of processes that know this open file. 

INO The location of the inode table entry for this file. 

OFFS/SOCK The file offset (see l8eek{2)), or the core address of the associated socket struc- 
ture. 

— ■ print information about swap space usage: the number of (Ik byte) pages used and free is 
given as well as the number of used pages which belong to text images. 

-T prints the number of used and free slots in the several system tables and is useful for check- 
ing to see how full system tables have become if the system b under heavy load. 
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FILES 

/vmunix namelist 

/dev/kmem default source of tables 

SEE ALSO 

ps(l), stat(2), fs(5) 

K. Thompson, UNIX Implementation 

BUGS 

It would be very useful if the system recorded "maximum occupancy" on the tables reported by 
~T; even more useful if these tables were dynamically allocated. 
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NAME 

quot - summarize file system ownership 

SYNOPSIS 

/etc/ quot ( option ] ... ( filesystem ] 

DESCRIPTION 

Quot prints the number of blocks in the named filesystem currently owned by each user. If no 
filesystem is named, a default name is assumed. 

OPTIONS 

-n Run the pipeline ncheck fllesystem | sort +0n | quot -n filesystem to produce a list 
of all files and their owners. 

-c Print three columns giving file size in blocks, number of files of that size, and cumulative 
total of blocks in that size or smaller file. 

-f Print count of number of files as well as space owned by each user. 

FILES 

Default file system varies with system, 
/etc/passwd to get user names 

SEE ALSO 

ls(l), du(l) 
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NAME 

re - command script for auto-reboot and daemons 

SYNOPSIS 

/etc/rc 
/etc/rctlocal 

DESCRIPTION 

Re is the command script which controls the automatic reboot and rc.local is the script holding 
commands which are pertinent only to a specific site. 

When an automatic reboot is in progress, re is invoked with the argument autoboot and runs a 
fsek with option -p to "preen" all the disks of minor inconsistencies resulting from the last sys- 
tem shutdown and to check for serious inconsistencies caused by hardware or software failure. If 
this auto-check and repair succeeds, then the second part of re is run. 

The second part of re, which is run after a auto-reboot succeeds and also if re is invoked when a 
single user shell terminates (see init(S)), starts all the daemons on the system, preserves editor 
files and clears the scratch directory /tmp. Rc.loeal is executed immediately before any other 
commands after a successful fsck. Normally, the first commands placed in the rc.local file define 
the machine's name, using ho8tname{l), and save any possible core image that might have been 
generated as a result of a system crash, 8aveeore(S). The latter command is included in the 
rc.local file because the directory in which core dumps are saved is usually site specific. 

SEE ALSO 

init(8), reboot(8), savecore(8) 
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NAME 

rdate - set system date from a remote host 

SYNOPSIS 

/usr/ucb/rdate hostname 

DESCRIPTION 

Rdate sets the local date and time from the hostname given as argument. You must be super-user 
on the local system. Typically rdate can be inserted as part of your /e<c/rc./oco/ startup script. 

SEE ALSQ 

timed(8C) 

BUGS 

Could be modified to accept a list of hostnames and try each until a valid date returned. Better 
yet would be to write a real date server that accepted broadcast requests. 

Version 1.1 of rdate is incompatible with version 1.0. rdate's issued on 1.1 systems will not get 
the time from systems running 1.0. 
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NAME 

reboot - UNIX bootstrapping procedures 

SYNOPSIS 

/etc/reboot { -n | [ -q 1 

DESCRIPTION 

The UNIX operating system is started by placing it in memory at location zero and transferring 
to zero. Since the system is not reenterable, it is necessary to read it in from disk or tape each 
time it is to be bootstrapped. 

Rebooting a running system. When a UNIX system is running and a reboot is desired, ehut- 
down{S) is normally used. If there are no users then /etc/reboot can be used. Reboot performs 
a sync operation on the disks, and then a multi-user reboot (as described below) is initiated. This 
causes a system to be booted and an automatic disk check to be performed. If all this succeeds 
without incident, the system is then brought up for many users. 

OPTIONS 

-n option avoids the sync. It can be used if a disk or the processor is on fire. 

-q reboots quickly and ungracefully, without first shutting down running processes. 

Power fail and crash recovery. Normally, the system will reboot itself at power-up or after 
crashes. Provided the auto-restart is enabled on the machine front panel, an automatic con- 
sistency check of the file systems will be performed then and unless this fails the system will 
resume multi-user operations. 

On both processors, the boot program finds the corresponding file on the given device, loads that 
file into memory location zero, and starts the program at the entry address specified in the pro- 
gram header (after clearing off the high bit of the specified entry address.) Normal line editing 
characters can be used in specifying the pathname. 

For tapes, the minor device number gives a file offset. 

FILES 

/vmunix system code 

/boot system bootstrap 

SEE ALSO 

crash(8S), fsck(8), init(8), rc(8), shutdown(8), halt(8), newf8(8) 
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NAME 

recnews - receive unprocessed articles via mail 

SYNOPSIS 

/usr/lib/news/recnews [ newsgroup \ sender ] ] 

DESCRIPTION 

I^ecnews reads a letter from the standard input; determines the article title, sender, and news* 
group; and gives the body to inews with the right arguments for insertion. 

If newsgroup is omitted, the to line of the letter is used. If sender is omitted, the sender is deter- 
mined from the from line of the letter. The title is determined from the subject line. 

SEE ALSO 

inews(l), uurec(8), 8endnews(8), readnews(l), checknews(l) 
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NAME 

renice - alter priority of running processes 

SYNOPSIS 

/etc/renice | -g ) | -u | priority who ... 

DESCRIPTION 

Renice can be used to alter the scheduling priority of one or more running processes. By default, 
. the processes to be affected are specified by their process id's. If the -g option is specified, the 
who parameters are interpreted as process groups and all the processes in the specified process 
groups have their scheduling priority altered. If the -u option is indicated, the who parameters 
ar^ interpreted as user names and all process owned by the user are affected. 

U5i?rs other than the super-user may only alter the priority of processes they own, and can only 
monotonically increase their "nice value" within the range to PRIO_MIN (20). (This prevents 
overriding administrative fiats.) The super-user may alter the priority of any process and set the 
priority to any value in the range PRIO_MAX (-20) to PRIO_MIN. Useful priorities are: 19 (the 
affected processes will run only when nothing else in the system wants to), (the "base" schedul- 
ing priority), anything negative (to make things go very fast). 

If no who parameter is specified, the current process (alternatively, process group or user) is used. 

FILES 

/etc/passwd to map user names to user id's 

SEE ALSO 

getpriority(2) 

BUGS 

If you make the priority very negative, then the process cannot be interrupted. To regain control 
you make the priority greater than zero. Non super-users can not increase scheduling priorities of 
their own processes, even if they were the ones that decreased the priorities in the first place. 
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NAME 

restore - incremental file system restore 

SYNOPSIS 

/etc/restore key [ name ... ] 

DESCRIPTION 

Restore restores files from tapes previously created via the dump{8) command. Restorers actions 
are controlled by the key argument. The key is a string of characters containing at most one func- 
tion letter and possibly one or more function modifiera. Other arguments to restore are file or 
directory names specifying the files that are to be restored. Unless the h key is specified (see 
below), the appearance of a directory name refers to the files and (recursively) subdirectories of 
that directory. 

FUNCTION LETTERS 

The function portion of the key is specified by one of the following letters: 

r The tape is read and loaded into the current directory. This should not be done lightly; the 
r key should only be used to restore a complete dump tape onto a clear file system or to 
restore an incremental dump tape after a full level zero restore. Thus: 

tutorial^ /ete/newfs /dev/rxyOg eagle 

tutorial% /etc/mount /dev/xyOg /mnt 

tutorial^ cd /mnt 

tutorial^ restore r 
is a typical sequence to restore a complete dump. Another restore can be done to get an 
incremental dump in on top of this. A dump{S) followed by a newfs{S) and a restore can be 
used to change the size of a file system. 

R Restore requests a particular tape of a multi volume set on which to restart a full restore 
(see the r key above). This allows restore to be interrupted and then restarted. 

X Extract the named files from the tape. If the named file matches a directory whose contents 
had been written onto the tape, and the h key is not specified, the directory is recursively 
extracted. The owner, modification time, and mode are restored (if possible). If no file 
argument is given, the root directory is extracted, which results in the entire content of the 
tape being extracted, unless the h key has been specified. 

t List the names of the specified files if they occur on the tape. If no file argument is given, 
the root directory is listed, which results in the entire content of the tape being listed, unless 
the h key has been specified. Note that the t key replaces the function of the old dumpdir 
program. 

I Restore files interactively from a dump tape. After reading in the directory information 
from the tape, restore provides a shell like interface within which the user can move around 
the directory tree selecting files to be extracted. The available commands that this 'shell' 
provides are given below. For those commands that require an argument, the default is the 
current directory. 

Is [argj List the current or specified directory. Entries that are directories are appended 
with a '/'• Entries that have been marked for extraction are prepended with a 
'*'. If the verbose key is set the inode number of each entry is also listed. 

cd arg Change the current working directory to the specified argument. 

pwd Print the full pathname of the current working directory. 

add [arg] Add the current directory or specified argument to the list of files to be 
extracted. If a directory is specified, add that directory and all its to the extrac- 
tion list (unless the h key is specified on the command line). Files that are on 
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the extraction list are prepended with a '*' when they are listed by Is. 

delete [arg] 

Delete the current directory or specified argument from the list of files to be 
extracted. If a directory is specified, delete that directory and all its descendents 
from the extraction list (unless the h key is specified on the command line). The 
most expedient way to extract most of the files from a directory is to add the 
directory to the extraction list and then delete those files that are not needed. 

extract Extract from the dump tape all the files that are on the extraction list. Restore 
asks which volume the user wishes to mount. The fastest way to extract a few 
files is to start with the last volume, and work towards the first volume. 

verbose Toggle the sense of the v key. When the verbose key is set, the Is command 
lists the inode numbers of all entries, and restore also displays information about 
each file as it is extracted. 

help List a summary of the available commands. 

quit Restore immediately exits, even if the extraction list is not empty. 

FUNCTION MODIFIERS 

The function modifiers which may be used in addition to the function letters are as follows. A 
few of these modifiers — namely b, f, and s — take an argument from the command line. If you 
use more than one of b, f, and s, nest your arguments as you do your modifiers; if you use b first 
on the command line, place its argument first on the command line, and so on. 

b Specifies the blocking factor for the restore. The blocking factor is taken from the next 
argument on the command line. This corresponds to the b key in dump{8). 

d Turns on debugging output. 

V This is the verbose option. It means display the name of each file it treats preceded by its 
file type. Restore normally works silently. 

f Use the next argument to restore as the name of the archive instead of /dev/rmt?. If the 
name of the file is '-', restore reads from standard input. If the name of the file is 
'machine:device' the restore is done from the specified machine through the internet using 
rmt{&C). Thus, dump{S) and restore can be used in a pipeline to dump and restore a file 
system with the command 

tutorial% dump Of- /usr | (ed /mnt; restore xf -) 

s The next argument to restore is the number of files to skip in the case where there are mul- 
tiple dump files on the dump tape. For example, a command like 

tutorial^ restore xfs /dev/nrarO 5 
would position you at the sixth file on the tape. 

y Do not ask whether to abort the restore in the event of tape errors. Restore always tries to 
skip over the bad tape block(s) and continue as best it can. 

m Extract by inode numbers rather than by file name. This is useful if only a few files are 
being extracted, and one wants to avoid regenerating the complete pathname to the file. 

h Extract the actual directory, rather than the files that it references. This prevents hierarch- 
ical restoration of complete subtrees from the tape. 

DIAGNOSTICS 

Complaints about bad key characters. 

Complaints if it gets a read error. If y has been specified, or the user responds 'y', restore will 
attempt to continue the restore. 
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If the dump extends over more than one tape, restore asks the user to change tapes. If the x or i 
key has been specified, restore also asks which volume the user wishes to mount. The fastest way 
to extract a few files is to start with the last volume, and work towards the first volume. 

There are numerous consistency checks that can be listed by restore. Most checks are self- 
explanatory or can 'never happen'. Common errors are given below. 

Converting to new file system format. 

A dump tape created from the old file system ha^ been loaded. It is automatically con- 
verted to the new file system format. 

<filename>: not found on tape 

The specified file name was listed in the tape directory, but was not found on the tape. 
This is caused by tape read errors while looking for the file, and from using a dump tape 
created on an active file system. 

expected next file <inumber>, got <inumber> 

A file that was not listed in the directory showed up. This can occur when using a dump 
tape created on an active file system. 

Incremental tape too low 

When doing incremental restore, a tape that was written before the previous incremental 
tape, or that has too low an incremental level has been loaded. 

Incremental tape too high 

When doing incremental restore, a tape that does not begin its coverage where the previous 
incremental tape left off, or that has too high an incremental level has been loaded. 

Tape read error while restoring <filename> 

Tape read error while skipping over inode <inumber> 

Tape read error while trying to resynchronize 

A tape read error has occurred. If a file name is specified, then its contents are probably 
partially wrong. If an inode is being skipped or the tape is trying to resynchronize, then no 
extracted files have been corrupted, though files may not be found on the tape. 

resync restore, skipped <num> blocks 

After a tape read error, restore may have to resynchronize itself. This message lists the 
number of blocks that were skipped over. 



FILES 



/dev/rmt? the default tape drive 

/tmp/rstdir* file containing directories on the tape, 
/tmp/rstmode* owner, mode, and time stamps for directories, 
./restoresymtab information passed between incremental restores. 

SEE ALSO 

dump(8), newfs(8), mount(8), mkfs(8), rmt(8C) 



BUGS 



Restore can get confused when doing incremental restores from dump tapes that were made on 
active file systems. 

A level zero dump must be done after a full restore. Because restore runs in user mode, it has no 
control over inode allocation; this means that restore re-positions the files, although it does 
change their contents. Thus, a full dump must be done to get a new set of directories reflecting 
the new file positions, so that later incremental dumps will be correct. 
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NAME 

rexecd - remote execution server 

SYNOPSIS 

/u8r/ete/ln.rexec<i host.port 

DESCRIPTION 

Rexecd is the server for the rexec(3N) routine. The server provides remote execution facilities 
with authentication based on user names and encrypted passwords. It is invoked automatically as 
needed by inetd{SC), and then executes the following protocol: 

1) The server reads characters from the socket up to a null ('\0') byte. The resultant string 
is interpreted as an ASCII number, base 10. 

2) If the number received in step 1 is non-zero, it is interpreted as the port number of a 
secondary stream to be used for the stderr. A second connection is then created to the 
specified port on the client's machine. 

3) A null terminated user name of at most 16 characters is retrieved on the initial socket. 

4) A null terminated, encrypted, password of at most 16 characters is retrieved on the initial 
socket. 

5) A null terminated command to be passed to a shell is retrieved on the initial socket. The 
length of the command is limited by the upper bound on the size of the system's argu- 
ment list. 

6) Rexecd then validates the user as is done at login time and, if the authentication was suc- 
cessful, changes to the user's home directory, and establbhes the user and group protec- 
tions of the user. If any of these steps fail the connection is aborted with a diagnostic 
message returned. 

7) A null byte is returned on the connection associated with the stderr and the command 
line is passed to the normal login shell of the user. The shell inherits the network connec- 
tions established by rexecd. 

DIAGNOSTICS 

All diagnostic messages are returned on the connection associated with the itderr, after which 
any network connections are closed. An error is indicated by a leading byte with a value of 1 (0 
is returned in step 7 above upon successful completion of all the steps prior to the command exe- 
cution). 

"user name too long" 

The naime is longer than 16 characters. 

"password too long** 

The password is longer than 16 characters. 

"command too long ** 

The command line passed exceeds the size of the argument list (as configured into the system). 

"Login Incorrect^** 

No password file entry for the user name existed. 

"Password Incorrect.** 

The wrong password was supplied. 

"!^Io remote directory." 

The chdir command to the home directory failed. 

"Try again.** 

A fork by the server failed. 
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"/bin/aht ..." 

The user's login shell could not be started. 

BUGS 

Indicating "Login incorrect" as opposed to "Password incorrect" is a security breach which allows 
people to probe a system for users with null passwords. 

A facility to allow all data exchanges to be encrypted should be present. 

SEE ALSO 

inetd(8C) 
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NAME 

rlogind - remote login server 

SYNOPSIS 

/etc/in.rlogind host. port 

DESCRIPTION 

Rlogind is the server for the rlogin{lC) program. The server provides a remote login facility with 
authentication based on privileged port numbers. 

Rlogind is invoked by inetd{SC) when a remote login connection is established, and executes the 
following protocol: 

1) The server checks the client's source port. If the port is not in the range 0-1023, the 
server aborts the connection. The client's address and port number are passed as argu- 
ments to rlogind by inetd in the form "host. port" with host in hex and port in decimal. 

2) The server checks the client's source address. If the address is associated with a host for 
which no corresponding entry exists in the host name data base (see ho8t8{b)), the server 
aborts the connection. 

Once the source port and address have been checked, rlogind allocates a pseudo terminal (see 
pty{4)), and manipulates file descriptors so that the slave half of the pseudo terminal becomes the 
■tdln I Btdout I and stderr for a login process. The login process is an instance of the login{l) 
program, invoked with the -r option. The login process then proceeds with the authentication 
process as described in r8hd{SC), but if automatic authentication fails, it reprompts the user to 
login as one finds on a standard terminal line. 

The parent of the login process manipulates the master side of the pseudo terminal, operating as 
an intermediary between the login process and the client instance of the rlogin program. In nor- 
mal operation, the packet protocol described in pty{\) is invoked to provide 'S/'Q type facilities 
and propagate interrupt signals to the remote programs. The login process propagates the client 
terminal's baud rate and terminal type, as found in the environment variable, "TERM"; see 
environ[h). 

DIAGNOSTICS 

All diagnostic messages are returned on the connection associated with the stderr, after which 
any network connections are closed. An error is indicated by a leading byte with a value of 1. 

"Hostname for your address unknown.** 

No entry in the host name database existed for the client's machine. 

"Try again«** 

A fork by the server failed. 

"/bln/sh: ...** 

The user's login shell could not be started. 

BUGS 

The authentication procedure used here assumes the integrity of each client machine and the con- 
necting medium. This is insecure, but is useful in an "open" environment. 

A facility to allow all data exchanges to be encrypted should be present. 

SEE ALSO 

inetd(8C) 
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NAME 

rmail - handle remote mail received via uucp 

SYNOPSIS 

rmail user ... 

DESCRIPTION 

Rmail interprets incoming mail received via uucp(lC), collapsing "From" lines in the form gen- 
erated by binmail{l) into a single line of the form "return-path!sender", and passing the processed 
mail on to 8endmail{8). 

Rmail is explicitly designed for use with uucp and sendmail. 

SEE ALSO 

binmail(l), uucp(lC), sendmail(8) 

BUGS 

Rmail should not reside in /bin. 
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NAME 

rmt - remote magtape protocol module 

SYNOPSIS 

/ete/rmt 

DESCRIPTION 

Rmt ia 2k program used by the remote dump and restor programs in manipulating a magnetic tape 
drive through an interprocess communication connection. Rmt is normally started up with an 
rcxcc(3N) or rcmrf(3N) call. 

The rmt program accepts requests specific to the manipulation of magnetic tapes, performs the 
commands, then responds with a status indication. All responses are in ASCII and in one of two 
forms. Successful commands have responses of 

Anum6er\n 

where number is an ASCII representation of a decimal number. Unsuccessful commands are 
responded to with 

Eierror-number\nerror-me88age\a, 

where error-number is one of the possible error numbers described in intro{2) and error-message is 
the corresponding error string as printed from a call to p error (3). The protocol is comprised of 
the following commands (a space is present between each token). 

device mode 

Open the specified device using the indicated mode. Device is a full pathname 
and mode is an ASCII representation of a decimal number suitable for passing to 
open{2). If a device had already been opened, it is closed before a new open is 
performed. 

C device Close the currently open device. The device specified is ignored. 

L whence offset 

Perform an l8eek{2) operation using the specified parameters. The response 
value is that returned from the Iseek call. 

W count Write data onto the open device. Rmt reads count bytes from the connection, 

aborting if a premature end-of-file is encountered. The response value is that 
returned from the write{2) call. 

R count Read count bytes of data from the open device. If count exceeds the size of the 

data buffer (10 kilobytes), it is truncated to the data buffer size. Rmt then per- 
forms the requested read(2) and responds with Acount-rea<l\n if the read was 
successful; otherwise an error in the standard format is returned. If the read was 
successful, the data read is then sent. 

1 operation count 

Perform a MTIOCOP ioctl{2) command using the specified parameters. The 
parameters are interpreted as the ASCII representations of the decimal values to 
place in the mt_op and mt_count fields of the structure used in the ioctl call. 
The return value is the count parameter when the operation is successful. 

S Return the status of the open device, as obtained with a MTIOCGET ioctl call. 

If the operation was successful, an "ack" is sent with the size of the status 
buffer, then the status buffer is sent (in binary). 

Any other command causes rmt to exit. 

DIAGNOSTICS 

All responses are of the form described above. 
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SEE ALSO 

rcmd(3N), rexec(3N), mtio(4), dump(8), restore(8) 

BUGS 

People tempted to use this for a remote file access protocol are discouraged. 
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NAME 

route - manually maaipulate the routing tables 

SYNOPSIS 

/uBP /etc/ route ( -f ] I command orgs \ 

DESCRIPTION 

Route is a program used to manually manipulate the network routing tables. It normally is not 
needed, as the system routing table management daemon, routed{SC), should tend to this task. 

Route accepts three commands: add, to add a route; delete, to delete a route; and change, to 
modify an existing route. 

All commands have the following syntax: 

/usr /etc/ route command destination gateway [ metric ] 

where destination is a host or network for which the route is "to", gateway is the gateway to 
which packets should be addressed, and metric is an optional count indicating the number of hops 
to the destination. If no metric is specified, route assumes a value of 0. Routes to a particular 
host are distinguished from those to a network by interpreting the Internet address associated 
with destination. If the destination has a "local address part" of INADDR_ANY, then the route 
is assumed to be to a network; otherwise, it is presumed to be a route to a host. If the route is to 
a destination connected via a gateway, the metric should be greater than 0. All symbolic names 
specified for a destination or gateway are looked up first in the host name database, ho8ts(b). If 
this lookup fails, the name is then looked for in the network name database, networks{b). 

Route uses a raw socket and the SIOCADDRT and SIOCDELRT ioctl'6 to do its work. As such, 
only the super-user may modify the routing tables. 

If the — f option is specified, route will "flush" the routing tables of all gateway entries. If this is 
used in conjunction with one of the commands described above, the tables are flushed prior to the 
command's application. 

DIAGNOSTICS 

"add %Bt gateway %u flags %x" 

The specified route is being added to the tables. The values printed are from the routing table 
entry supplied in the ioctl call. 

"delete %bi gateway %s flags %x" 
As above, but when deleting an entry. 

"%s %B done" 

When the -f flag is specified, each routing table entry deleted is indicated with a message of this 

form. 

"not in table" 

A delete operation was attempted for an entry which wasn't present in the tables. 

"routing table overflow" 

An add operation was attempted, but the system was low on resources and was unable to allocate 

memory to create the new entry. 

SEE ALSO 

routing(4N), routed(8C) 

BUGS 

The change operation is not implemented, one should add the new route, then delete the old one. 
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NAME 

routed - network routing daemon 

SYNOPSIS 

/usr/etc/in.routed j -■ ] ( -q 1 ( -t J [ logfile ] 

DESCRIPTION 

Routed is invoked at boot time to manage the network routing tables. The routing daemon uses 
a, variant of the Xerox NS Routing Information Protocol in maintaining up to date kernel routing 
table entries. 

lift normal operation routed listens on udp{iP) socket 520 (decimal) for routing information pack- 
ets. If the host is an internetwork router, it periodically supplies copies of its routing tables to 
amy directly connected hosts and networks. 

When routed is started, it uses the SIOCGIFCONF ioctl to find those directly connected inter- 
faces configured into the system and marked "up" (the software loopback interface is ignored). If 
multiple interfaces are present, it is assumed the host will forward packets between networks. 
Routed then transmits a request packet on each interface (using a broadcast packet if the inter- 
face supports it) and enters a loop, listening for request and response packets from other hosts. 

When a request packet is received, routed formulates a reply based on the information maintained 
in its internal tables. The response packet generated contains a list of known routes, each 
marked with a "hop count" metric (a count of 16, or greater, is considered "infinite"). The 
metric associated with each route returned provides a metric relative to the sender. 

Request packets received by routed are used to update the routing tables if one of the following 
conditions is satisfied: 

(1) No routing table entry exists for the destination network or host, and the metric indicates 
the destination is "reachable" (that is, the hop count is not infinite). 

(2) The source host of the packet is the same as the router in the existing routing table 
entry. That is, updated information is being received from the very internetwork router 
through which packets for the destination are being routed. 

(3) The existing entry in the routing table has not been updated for some time (defined to be 
90 seconds) and the route is at least as cost effective as the current route. 

(4) The new route describes a shorter route to the destination than the one currently stored 
in the routing tables; the metric of the new route is compared against the one stored in 
the table to decide this. 



len an update is applied, routed records the change in its internal tables and generates a 
response packet to all directly connected hosts and networks. Routed waits a short period of time 
(no more than 30 seconds) before modifying the kernel's routing tables to allow possible unstable 
situations to settle. 

In addition to processing incoming packets, routed also periodically checks the routing table 
entries. If an entry has not been updated for 3 minutes, the entry's metric is set to infinity and 
marked for deletion. Deletions are delayed an additional 60 seconds to insure the invalidation is 
propagated throughout the internet. 

Hosts acting as internetwork routers gratuitously supply their routing tables every 30 seconds to 
all directly connected hosts and networks. 

Supplying the -s option forces routed to supply routing information whether it is acting as an 
internetwork router or not. The -q option is the opposite of the -s option. If the -t option is 
specified, all packets sent or received are printed on the standard output. In addition, routed will 
not divorce itself from the controlling terminal so that interrupts from the keyboard will kill the 
process. Any other argument supplied is interpreted as the name of file in which routed's actions 
should be logged. This log contains information about any changes to the routing tables and a 
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history of recent messages sent and received which are related to the changed route. 

In addition to the facilities described above, routed supports the notion of "distant" passive and 
active gateways. When routed is started up, it reads the file /etc/ gateways to find gateways which 
may not be identified using the SIOGIFCONF ioctl. Gateways specified in this manner should be 
marked passive if they are not expected to exchange routing information, while gateways marked 
active should be willing to exchange routing information (that is, they should have a routed pro- 
cess running on the machine). Passive gateways are maintained in the routing tables forever and 
information regarding their existence b included in any routing information transmitted. Active 
gateways are treated equally to network interfaces. Routing information is dbtributed to the 
gateway and if no routing information is received for a period of the time, the associated route is 
deleted. 

The /etc/ gateways is comprised of a series of lines, each in the following format: 

< net I hoit > namel gateway name8 metric value < passive | active > 

The net or host keyword indicates if the route is to a network or specific host. 

Namel is the name of the destination network or host. This may be a symbolic name located in 
/etc/networks or /etc/ hosts, or an Internet address specified in "dot" notation; see me{(3N). 

Name8 is the name or address of the gateway to which messages should be forwarded. 

Value is a metric indicating the hop count to the destination host or network. 

The keyword passive or active indicates if the gateway should be treated as passive or active (as 
described above). 



FILES 



/etc/gateways for distant gateways 

SEE ALSO 

Internet Transport Protocols, XSIS 028112, Xerox System Integration Standard. (Sun 800-1066- 

01) 

udp(4P) 



BUGS 



The kernel's routing tables may not correspond to those of routed for short periods of time while 
processes utilizing existing routes exit; the only remedy for this is to place the routing process in 
the kernel. 

Routed should listen to intelligent interfaces, such as an IMP, and to error protocols, such as 
ICMP, to gather more information. 
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NAME 

rshd - remote shell server 

SYNOPSIS 

/ete/in.r8hd host. port 

DESCRIPTION 

Rshd is the server for the rcmd{SN) routine and, consequently, for the r8h(lC) program. The 
server provides remote execution facilities with authentication based on privileged port numbers. 

Rshd is invoked by inetd{SC) each time a shell service is requested, and executes the following 
protocol: 

1) The server checks the client's source port. If the port is not in the range 0-1023, the 
server aborts the connection. The clients host address (in hex) and port number (in 
decimal) are the argument passed to rshd. 

2) The server reads characters from the socket up to a null ('\0') byte. The resultant string 
is interpreted as an ASCII number, base 10. 

3) If the number received in step 1 is non-zero, it is interpreted as the port number of a 
secondary stream to be used for the stderr. A second connection is then created to the 
specified port on the client's machine. The source port of this second connection is also 
in the range 0-1023. 

4) The server checks the client's source address. If the address is associated with a host for 
which no corresponding entry exists in the host name data base (see ho8t8{b)), the server 
aborts the connection. 

5) A null terminated user name of at most 16 characters is retrieved on the initial socket. 
This user name is interpreted as a user identity to use on the server's machine. 

6) A null terminated user name of at most 16 characters is retrieved on the initial socket. 
This user name is interpreted as the user identity on the client's machine. 

7) A null terminated command to be passed to a shell is retrieved on the initial socket. The 
length of the command is limited by the upper bound on the size of the system's argu- 
ment list. 

8) Rshd then validates the user according to the following steps. The remote user name is 
looked up in the password file and a chdir is performed to the user's home directory. If 
the lookup or fails, the connection is terminated. If the chdir fails, it does a chdir to / 
(root). If the user is not the super-user, (user id 0), the file /etc/ hosts. equiv is consulted 
for a list of hosts considered "equivalent". If the client's host name is present in this file, 
the authentication is considered successful. If the lookup fails, or the user is the super- 
user, then the file .rhosts in the home directory of the remote user is checked for the 
machine name and identity of the user on the client's machine. If thb lookup fails, the 
connection is terminated. 

9) A null byte is returned on the connection associated with the stderr and the command 
line is passed to the normal login shell of the user. The shell inherits the network connec- 
tions established by rshd. 

DIAGNOSTICS 

All diagnostic messages are returned on the connection associated with the stderr, after which 
any network connections are closed. An error is indicated by a leading byte with a value of 1 (0 
is returned in step 9 above upon successful completion of all the steps prior to the command exe- 
cution). 

"locuser too long" 

The name of the user on the client's machine is longer than 16 characters. 
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"remuser too long'* 

The name of the user on the remote machine is longer than 16 characters. 

"command too long *' 

The command line passed exceeds the size of the argument list (as configured into the system). 

"Hostname for your address unknown.'* 

No entry in the host name database existed for the client's machine. 

"Login incorrect.** 

No password file entry for the user name existed. 

"Permission denied.'* 

The authentication procedure described above failed. 

"Can*t make pipe." 

The pipe needed for the stderr, wasn't created. 

"Try again.** 

A fork by the server failed. 

"/bin/slii ...*• 

The user's login shell could not be started. 

SEE ALSO 

r8h(lC), rcmd(3N) 

BUGS 

The authentication procedure used here assumes the integrity of each client machine and the con- 
necting medium. This is insecure, but is useful in an "open" environment. 

A facility to allow all data exchanges to be encrypted should be present. 
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NAME 

rwhod - system status server 

SYNOPSIS 

/etc/rwhod 

DESCRIPTION 

Rwhod is the server which maintains the database used by the rwko{lC) and ruptime{lC) pro- 
grams. Its operation is predicated on the ability to broadcast messages on a network. 

Rwhod operates as both a producer and consumer of status information. As a producer of infor- 
mation it periodically queries the state of the system and constructs status messages which are 
broadcast on a network. As a consumer of information, it listens for other rwhod servers' status 
messages, validating them, then recording them in a collection of files located in the directory 
/usr/spoot/rwho. 

The rwho server transmits and receives messages at the port indicated in the "rwho" service 
specification, see service8{5). The messages sent and received, are of the form: 

struct outmp { 

char out_line(8); /* tty name */ 

char out_name(8|; /* user id */ 

long out_time; /* time on */ 

}; 

struct whod { 

char wd_ver8; 
char wd_type; 
char wd_fill|2J; 
int wdjsendtime; 
int wd_recvtime; 

char wd_hostname[32]; 
int wd_loadav(3); 
int wd_boottime; 
struct whoent { 

struct outmp we_utmp; 

int we_idle; 

} wd wejl024 / sizeof (struct whoent)]; 

}; 

All fields are converted to network byte order prior to transmission. The load averages are as cal- 
culated by the w{l) program, and represent load averages over the 5, 10, and 15 minute intervals 
prior to a server's transmission. The host name included is that returned by the getho8tname{2) 
system call. The array at the end of the message contains information about the users logged in 
to the sending machine. This information includes the contents of the utmp{S) entry for each 
non-idle terminal line and a value indicating the time since a character was last received on the 
terminal line. 

Messages received by the rwho server are discarded unless they originated at a rwho server's port. 
In addition, if the host's name, as specified in the message, contains any unprintable ASCII char- 
acters, the message is discarded. Valid messages received by rwhod are placed in files named 
whod.hoetname in the directory /usr/ spool/ rwho. These files contain only the most recent mes- 
sage, in the format described above. 

Status messages are generated approximately once every 60 seconds. Rwhod performs an ntist{3) 
on /vmunix every 10 minutes to guard against the possibility that this file is not the system 
image currently operating. 
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SEE ALSO 

rwho(lC), ruptime(lC) 

BUGS 

Should relay status information between networks. People often interpret the server dying as a 
machine going down. 
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NAME 

sa, accton - system accounting 

SYNOPSIS 

/usr/etc/sa [ -abcdD^kKInrstuv ] | file ] 

/usr/etc/ accton [ file ] 

DESCRIPTION 

With an argument naming an existing file, accton causes ^stem accounting information for every 
process executed to be placed at the end of the file. If no argument is given, accounting is turned 
off. 

Sa reports on, cleans up, and generally maintains accounting files. 

Sa is able to condense the information in /usr/adm/acct into a summary file /uar/adm/savacct 
which contains a count of the number of times each command was called and the time resources 
consumed. This condensation is desirable because on a large system /usr/adm/acct can grow by 
500K bytes per day. The summary file is normally read before the accounting file, so the reports 
include all available information. 

If a file name is given as the last argument, that file will be treated as the accounting file; 
/usr/adm/acct is the default. 

Output fields are labelled: 'cpu' for the sum of user+ system time (in minutes), 're' for real time 
(also in minutes), 'k' for cpu-time averaged core usage (in Ik units), 'avio' for average number of 
I/O operations per execution. With options fields labelled 'tio' for total I/O operations, 'k*sec' 
for cpu storage integral (kilo-core seconds), 'u' and 's' for user and system cpu time alone (both in 
minutes) will sometimes appear. 

OPTIONS 

a Place all command names containing unprintable characters and those used only once 

under the name '***other.' 

b Sort output by sum of user and system time divided by number of calls. Default sort is 

by sum of user and system times. 

c Besides total user, system, and real time for each command print percentage of total time 

over all commands. 

d Sort by average number of disk I/O operations. 

D Print and sort by total number of disk I/O operations. 

f Force no interactive threshold compression with -v flag. 

i Don't read in summary file. 

j Instead of total minutes time for each category, give seconds per call. 

k Sort by cpu-time average memory usage. 

K Print and sort by cpu-storage integral. 

1 Separate system and user time; normally they are combined. 

m Print number of processes and number of CPU minutes for each user. 

n Sort by number of calls. 

r Reverse order of sort. 

8 Merge accounting file into summary file /usr/adm/savacct when done. 

t For each command report ratio of real time to the sum of user and system times. 

u Superseding all other flags, print for each record in the accounting file the user ID and 

command name. 
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V Followed by a number n, types the name of each command used n times or fewer. Await 

a reply from the terminal; if it begins with 'y', add the command to the category 
'♦♦junk**.' This is used to strip out garbage. 

FILES 

/usr/adm/acct raw accounting 

SEE ALSO 

ac(8), acct(2), acct(5), 8avacct(5), U8racct(5) 
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NAME 

savecore - save a core dump of the operating system 

SYNOPSIS 

/usr/etc/savecore dirname ( system ] 

DESCRIPTION 

Savecore is meant to be called near the end of the /etc/ re file after the system boots. Savecore' s 
function is to save the core dump of the system (assuming one >vas made) and to write a reboot 
message in the shutdown log. 

Savecore checks the core dump to be certain it corresponds with the current running version of 
the operating system. If it does, savecore saves the core image in the file (/trname/vmcore.n and 
its brother, the namelist, <ftrname/vmunix.n The trailing .n in the pathnames is replaced by a 
number which grows every time savecore is run in that directory. 

Before savecore writes out a core image, it reads a number from the file (/trname/minfree. If 
there less free space on the filesystem which contains dirname than the number obtained from the 
minfree file, the core dump is not done. If the minfree file does not exist, savecore always writes 
out the core file (assuming that a core dump was taken). 

Savecore also writes a reboot message in the shut down log. If the system crashed as a result of a 
panic, savecore records the panic string in the shut down log too. 

If the core dump was from a system other than /vmunix, the name of that system must be sup- 
plied as sysname. 



FILE& 



BUGS 



/usr/adm/shutdownlog shut down log 

/usr/crash/bounds number to assign to the core images 

/vmunix current UNIX 

Can be fooled into thinking a core dump is the wrong size. 
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NAME 

sendmail - send mail over the internet 

SYNOPSIS 

/uBr/lib/sendmaU | ~ba ] | -bd ) | -bl | | -bm ] | -bp 
[ -Cfile I I -dX] I -Ffullname ] | -tname ] [ -hTVJ 
I -rname ] | -t ] | -v ] [ address ... j 

DESCRIPTION 

Sendmail sends a message to one or more people, routing the message over whatever networks are 
necessary. Sendmail does internetwork forwarding as necessary to deliver the message to the 
correct place. 

Sendmail is not intended as a user interface routine; other programs provide user-friendly front 
ends; sendmail is used only to deliver pre-formatted messages. 

With no flags, sendmail reads its standard input up to a control-D or a line with a single dot and 
sends a copy of the letter found there to all of the addresses listed. It determines the network to 
use based on the syntax and contents of the addresses. 

Local addresses are looked up in a file and aliased appropriately. Aliasing can be prevented by 
preceding the address with a backslash. Normally the sender is not included in any alias expan- 
sions, for example, if 'John' sends to 'group', and 'group' includes 'John' in the expansion, then 
the letter will not be delivered to 'John*. 



OPTIONS 
-ba 



-bd 

-bl 

-bm 

-bp 

-bs 



-bt 
-bv 

-bl 

-Cfile 
-dX 

—Ffullname 
-tname 

-hN 

-n 

—ox value 



Go into ARPANET mode. All input lines must end with a CR-LF, and all 
messages will be generated with a CR-LF at the end. Also, the "From:" and 
"Sender:" fields are examined for the name of the sender. 

Run as a daemon. This requires Berkeley IPC. 

Initialize the alias database. 

Deliver mail in the usual way (default). 

Print a summary of the mail queue. 

Use the SMTP protocol as described in RFC821. This flag implies all the 
operations of the -ba flag that are compatible with SMTP. 

Run in address test mode. This mode reads addresses and shows the steps in 
parsing; it is used for debugging configuration tables. 

Verify names only - do not try to collect or deliver a message. Verify mode is 
normally used for validating users or mailing lists. 

Create the configuration freeze file. 

Use alternate configuration file. 

Set debugging value to X. 

Set the full name of the sender. 

Sets the name of the "from" person (that is, the sender of the mail), -t can 
only be used by the special users root, daemon, and network, or if the person 
you are trying to become b the same as the person you are. 

Set the hop count to N. The hop count is incremented every time the mail is 
processed. When it reaches a limit, the mail is returned with an error mes- 
sage, the victim of an aliasing loop. 

Don't do aliasing. 

Set option x to the specified value. Options are described below. 
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SENDMAIL(8) 



-q| time ) 



—rname 
-t 



-V 



Processed saved messages in the queue at given intervals. If time is omitted, 
process the queue once. Time is given as a tagged number, with 's' being 
seconds, 'm' being minutes, 'h' being hours, 'd' being days, and 'w' being 
weeks. For example, "-qlhSOm" or "-q90m" would both set the timeout to 
one hour thirty minutes. 

An alternate and obsolete form of the -f flag. 

Read message for recipients. To:, Cc:, and Bcc: lines will be scanned for peo- 
ple to send to. The Bcc: line will be deleted before transmission. Any 
addresses in the argument list will be suppressed. 

Go into verbose mode. Alias expansions will be announced, etc. 



PROCESSING OPTIONS 

There are also a number of processing options that may be set. Normally these will only be used 
by a system administrator. Options may be set either on the command line using the -o flag or 
in the configuration file. These are described in detail in the Installation and Operation Guide. 
The options are: 



Afite 
c 

dx 

D 
ex 



Fmode 
f 

Hfiie 

i 

Ln 

m 

o 



Qqueuedir 
Ttimeout 
Sfile 
s 



Use alternate alias file. 

On mailers that are considered "expensive" to connect to, don't initiate 
immediate connection. This requires queueing. 

Set the delivery mode to x. Delivery modes are 'i' for interactive (synchro- 
nous) delivery, 'b' for background (asynchronous) delivery, and 'q' for queue 
only - that is, actual delivery is done the next time the queue is run. 

Try to automatically rebuild the alias database if necessary. 

Set error processing to mode x. Valid modes are 'm' to mail back the error 
message, 'w' to "write" back the error message (or mail it back if the sender 
is not logged in), 'p' to print the errors on the terminal (default), 'q' to throw 
away error messages (only exit status is returned), and 'e' to do special pro- 
cessing for the BerkNet. If the text of the message is not mailed back by 
modes 'm' or 'w' and if the sender is local to this machine, a copy of the me»- 
sage is appended to the file "dead. letter" in the sender's home directory. 

The mode to use when creating temporary files. 

Save UNIX-style From lines at the front of messages. 

The default group id to use when calling mailers. 

The SMTP help file. 

Do not take dots on a line by themselves as a message terminator. 

The log level. 

Send to "me" (the sender) also if I am in an alias expansion. 

If set, this message may have old style headers. If not set, this message is 
guaranteed to have new style headers (that is, commas instead of spaces 
between addresses). If set, an adaptive algorithm is used that will correctly 
determine the header format in most cases. 

Select the directory in which to queue messages. 

The timeout on reads; if none is set, sendmail will wait forever for a mailer. 

Save statistics in the named file. 

Always instantiate the queue file, even under circumstances where it is not 
strictly necessary. 
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Ttime Set the timeout on messages in the queue to the specified time. After sitting 

in the queue for this amount of time, they will be returned to the sender. The 
default is three days. 

UtZfdtz Set the name of the time zone. 

mN Set the default user id for mailers. 

If the first character of the user name is a vertical bar, the rest of the user name is used as the 
name of a program to pipe the mail to. It may be necessary to quote the name of the user to 
keep sendmail from suppressing the blanks from between arguments. 

Sendmail returns an exit status describing what it did. The codes are defined in <8y8exit8.h> 

EX_OK Successful completion on all addresses. 

EX_NOUSER User name not recognized. 

EX_UNAVAILABLE Catchall meaning necessary resources were not available. 

EX_SYNTAX Syntax error in address. 

EX_S OFT WARE Internal software error, including bad arguments. 

EX_OSERR Temporary operating system error, such as "cannot fork". 

EX_NOHOST Host name not recognized. 

EXJTEMPFAIL Message could not be sent immediately, but was queued. 

If invoked as newaliasea, sendmail rebuilds the alias database. If invoked as mailq, sendmail 
prints the contents of the mail queue. 



FILES 



Except for / usr/ lib/ sendmail. cf, these pathnames are all specified in / usr/ lib/ sendmail. cf. Thus, 
th^se values are only approximations. 

/u|ir/lib/aliases raw data for alias names 
/iffr/lib/aliases.pag 

/Mpr/lib/aliases.dir data base of alias names 

/upr/lib/sendmail.cf configuration file 

/usr/lib/sendmail.fc frozen configuration 

/usr/lib/sendmail.hf help file 

/usr/lib/sendmail.st collected statistics 

/usr/bin/uux to deliver uucp mail 

/bin/madl to deliver local mail 

/usr/spool/mqueue/* temp files and queued mail 

SEE ALSO 

bi£f(l), binmail(l), mail(l), aliases(5), 

DARPA Internet Request For Comments RFC819, RFC821, RFC822, 

In the System Manager's Manual: 

Setting Up the Mail System in the System Set-up and Operation chapter. 
Sendmail - An Internetwork Mail Router, in the Tutorials section 
Sendmail Installation and Operation Guide, in the Tutorials section 



BUGS 



Sendmail converts blanks in addresses to dots. This is incorrect according to the old ARPANET 
mail protocol RFC733 (NIC 41952), but is consistent with the new protocols (RFC822). 
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NAME 

sendnews - send news articles via mail 

SYNOPSIS 

sendnews [ -o ] { -a ] [ -b ] [ -n newsgroups ] destination 

DESCRIPTION 

sendnews reads an article from it's standard input, performs a set of changes to it, and gives it to 
the mail program to mail it to destination. 

An 'N' is prepended to each line for decoding by uuree(l). 

OPTIONS 

-o handle old format articles. 

-a used for sending articles via the ARPANET. It maps the article's path from uucphostlxxx 
to xxx&arpahost. 

—h used for sending articles via the Berknet. It maps the article's path from uucphostlxxx 
to berkhosttxxx. 

— n change the article's newsgroup to the specified newsgroup. 

SEE ALSO 

inews(l), uurec(8), recnews(8), readnews(l), checknews(l) 
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NAME 

shutdown - close down the system at a given time 

SYNOPSIS 

/etc/shutdown [ -k | [ -r ] [ -h ] time ( warning-message ... ] 

DESCRIPTION 

Shutdown provides an automated shutdown procedure which a super-user can use to notify users 
nicely when the system is shutting down, saving them from system administrators, hackers, and 
gurus, who would otherwise not bother with niceties. 

Time is the time at which shutdown will bring the system down and may be the word now (indi- 
cating an immediate shutdown) or specify a future time in one of two formats: -(-number and 
hour:min. The first form brings the system down in number minutes and the second brings the 
system down at the time of day indicated (as a 24-hour clock). 

At intervals which get closer together as apocalypse approaches, warning messages are displayed 
at the terminals of ail users on the system. Five minutes before shutdown, or immediately if 
shutdown is in less than 5 minutes, logins are disabled by creating /etc/notogin and writing a 
message there. If this file exists when a user attempts to log in, login(l) prints its contents and 
exits. The file is removed just before shutdown exits. 

At shutdown time a message is written in the file /usr/adm/shutdownlog, containing the time of 
shutdown, who ran shutdown and the reason. Then a terminate signal is sent at init to bring the 
system down to single-user state. 

The time of the shutdown and the warning message are placed in /etc/nologin and should be used 
to inform the users about when the system will be back up and why it is going down (or anything 
else). 

OPTIONS 

As an alternative to the above procedure, these options can be specified: 

— r Execute reboot{S). 

-h Execute haU{8). 

-k. If it isn't obvious, -k is to make people think the system is going down! 

FILES 

/etc/nologin tells login not to let anyone log in 
/usr/adm/shutdownlog log file for succesful shutdowns. 

SEE ALSO 

login(l), reboot(8) 

BUGS 

Only allows you to kill the system between now and 23:59 if you use the absolute time for shut- 
down. 
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NAME 

sticky - executable files with persistent text 

DESCRIPTION 

While the 'sticky bit', mode 01000 (see chmod{2)), is set on a sharable executable file, the text of 
that file will not be removed from the ^stem swap area. Thus the file does not have to be 
fetched from the file system upon each execution. As long as a copy remains in the swap area, 
the original text cannot be overwritten in the file system, nor can the file be deleted. Directory 
entries can be removed so long as one link remains. 

Sharable files are made by the -s option of ld{l). 

To replace a sticky file that has been used do: (1) Clear the sticky bit with ckmod{l). (2) Execute 
the old program to flush the swapped copy. This can be done safely even if others are using it. 
(3) Overwrite the sticky file. If the file is being executed by any process, writing will be 
prevented; it suffices to simply remove the file and then rewrite it, being careful to reset the 
owner and mode with chmod and chown{2). (4) Set the sticky bit again. 

Only the super-user can set the sticky bit. 
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NAME 

swapon - specify additional device for paging and swapping 

SYNOPSIS 

/usr/etc/swapon -a 
/usr/ete/iwapon name ... 

DESCRIPTION 

Swapon is used to specify additional devices on which paging and swapping are to take place. 
The system begins by swapping and paging on only a single device so that only one disk is 
required at bootstrap time. Calls to swapon normally occur in the system multi-user initialization 
file /etc/ re making all swap devices available, so that the paging and swapping activity is inter- 
leaved across several devices. 

Normally, the -a argument is given, causing all devices marked as "sw" swap devices in 
/ete/fiitab to be made available. 

The second form gives individual block devices as given in the ^stem swap configuration table. 
The call makes only this space available to the system for swap allocation. 

SEE ALSO 

swapon(2), init(8) 

FILES 

/dev/[ru][pk]?b normal paging devices 

BUGS 

There is no way to stop paging and swapping on a device. It is therefore not possible to make use 
of devices which may be dismounted during system operation. 
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NAME 

sync - update the super block 

SYNOPSIS 
sync 

DESCRIPTION 

Sync executes the sync system primitive. Sync can be called to insure all disk writes have been 
completed before the processor is halted in a way not suitably done by reboot{S) or halt(S). 

See 8ync{2) for details on the system primitive. 

SEE ALSO 

8ync(2), fsync(2), halt(8), reboot(8) 
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NAME 

syslog - log systems messages 

SYNOPSIS 

/usr /etc/ in.By slog | -miV ) ( -tname J ( -d | 

DESCRIPTION 

Syslog reads a datagram socket and logs each message it reads into a set of files described by the 
configuration file /etc/ayslog.conf. Syslog configures when it starts up and whenever it receives a 
hangup signal. Syslog logs to the host specified by 'loghost' in the /etc/ hosts file. For details on 
running syslog in a Sun network environment, see the section, "System Log Configuration" in the 
System Set-up and Operation chapter of the System Installation and Maintenance Guide. 

Each message logged consists of one line. A message can contain a priority code, marked by a 
digit in angle braces at the beginning of the line. Priorities are defined in <syslog.h>, as defined 
in the list below. LOG_ALERT is prioity 1 (the highest priority) while LOG_DEBUG is priority 
(the lowest priority). 

LOG_ALERT this priority should essentially never be used. It applies only to messages that 

are so important that every user should be aware of them, for example, a 
serious hardware failure. 

LOG_SALERT messages of this priority should be issued only when immediate attention is 
needed by a qualified system person, for example, when some valuable system 
resource disappears. They get sent to a list of system people. 

Emergency messages are not sent to users, but represent major conditions. 
An example might be hard disk failures. These could be logged in a separate 
file so that critical conditions could be easily scanned. 

these represent error conditions, such as soft disk failures, etc. 

such messages contain critical information, but which can not be classed as 
errors, for example, 'su' attempts. Messages of this priority and higher are 
typically logged on the system console. 

issued when an abnormal condition has been detected, but recovery can take 
place. 

something that falls in the class of "important information;" this class is 
informational but important enough that you don't want to throw items in it 
away casually. Messages without any priority assigned to them are typically 
mapped into this priority. 

information level messages. These messages could be thrown away without 
problems, but should be included if you want to keep a close watch on your 
system. 

it may be useful to log certain debugging information. Normally this will be 
thrown away. 

It is expected that the kernel will not log anything below LOG_ERR priority. 

The syslog configuration file, etc/ syslog, conf, consists of two sections separated by a blank line. 
The first section defines files that syslog will log into. Each line contains a single digit which 
defines the lowest priority (highest numbered priority) that this file will receive, an optional aster- 
isk which guarantees that something gets output at least every 20 minutes, and a pathname. The 
second part of the file contains a list of users that will be informed on SALERT level messages. 
For example, the configuration file: 

5*/dev/tty8 

8/usr /spool/ adm/syslog 



LOG EMERG 



LOG_ERR 
LOG CRIT 



LOG_WARNING 



LOG NOTICE 



LOG INFO 



LOG.DEBUG 



102 



Last change: 16 February 1984 



Sun Release 1.1 



S YSL OG ( 8 ) MAINTENANCE COMMANDS S YSL OG ( 8 ) 



3/usr/adm/critical 

eric 

kridle 

kalash 

logs all messages of priority 5 or higher onto the system console, including timing marks every 20 
minutes; all messages of priority 8 or higher into the file fusr/ spool/ adm/syslog; and all messages 
of priority 3 or higher into / uerf admf critical. The users 'eric', 'kridle', and 'kalash' will be 
informed on any subalert messages. 

OPTIONS 

-m N Set the mark interval to N (default 20 minutes). 

—tname 

Specify an alternate configuration file. 

-d Turn on debugging (if compiled in). 

-pport Port number where syslog listens for incoming datagrams. The default port is defined in 
the 'syslog/udp' entry in the / etc/ services file. 

To bring syslog down, it should be sent a terminate signal. It logs that it is going down and then 
waits approximately 10 seconds for any additional messages to come in. 

There are some special messages that cause control functions. '<*>N' sets the default message 
priority to N. '<$>' causes syslog to reconfigure (equivalent to a hangup signal). This can be 
used in a shell file run automatically early in the morning to truncate the log. 

Syslog creates the file /etc/syslog.pid if possible containing a single line with its process id. This 
can be used to kill or reconfigure syslog. 

FILES 

/etc/hosts - the hosts file 

/etc/syslog.conf - the configuration file 

/etc/syslog.pid - the process id 

/etc/services - to find the syslog server's port number. 

BUGS 

LOG_ALERT and LOG_SALERT messages should only be allowed to privileged programs. 

Actually, syslog is not clever enough to deal with kernel error messages in the current implemen- 
tation. 

SEE ALSO 

sy8log(3), kill(2) 
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NAME 

telnetd - DARPA TELNET protocol server 

SYNOPSIS 

/uBr/etc/in.telnetd host. port 

DESCRIPTION 

Telnetd is a server which supports the DARPA standard TELNET virtual terminal protocol. The 
TELNET server is invoked by inetd(8C) each time there is a connection to the telnet service; see 
8ervice8{5). 

Telnetd operates by allocating a pseudo-terminal device (see pty{i)) for a client, then creating a 
login process which has the slave side of the pseudo-terminal as stdin, stdout, and stderr. Tel- 
netd manipulates the master side of the pseudo terminal, implementing the TELNET protocol 
and passing characters between the client and login process. 

When a TELNET session is started up, telnetd sends a TELNET option to the client side indicat- 
ing a willingness to do "remote echo" of characters. The pseudo terminal allocated to the client 
is configured to operate in "cooked" mode, and with XTABS and CRMOD enabled (see ff!/(4)). 
Aside from this initial setup, the only mode changes telnetd will carry out are those required for 
echoing characters at the client side of the connection. 

Telnetd supports binary mode, and most of the conmion TELNET options, but does not, for 
instance, support timing marks. 

SEE ALSO 

telnet(lC) 

BUGS 

A complete Ibt of the options supported should be given here. 
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NAME 

tftpd - DARPA Trivial File Transfer Protocol server 

SYNOPSIS 

/usr/etc/tftpd ( -d ) [ port ] 

DESCRIPTION 

Tftpd is a server which supports the DARPA Trivial File Transfer Protocol. The TFTP server 
operates at the port indicated in the "tftp" service description; see 8ervice8{b), and is invoked 
each time a datagram reaches this port by the internet server inetd{8C). 

Due to the lack of authentication information, tftpd will allow only publicly readable files to be 
accessed. 

SEE ALSO 

tftp(lC) 

BUGS 

This server is known only to be self consistent (i.e. it operates with the user TFTP program, 
tftp(lC)). 
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NAME 

timed - DARPA Time server 

SYNOPSIS 

/uBr/etc/in.tlmed 

DESCRIPTION 

Timed is a server which supports the DARPA Time Server Protocol. The time server operates at 
the port indicated in the "time" service description; see 8ervice8{b), and is invoked by inetd{SC) 
each time there is a connection to the time server. 

SEE ALSO 

8ervices(5), rdate(8), inetd(8) 

BUGS 

A more sophisticated facility that can accept broadcasts and synchronize clocks over an internet 
is needed. 
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NAME 

trpt - transliterate protocol trace 

SYNOPSIS 

/usr/etc/trpt | -a j ( -■ ] ( -t ] ( -J | ( -phex-addreea ) [ system | core ] j 

DESCRIPTION 

Trpt interrogates the buffer of TCP trace records created when a socket is marked for 'debugging' 
(see 8et8ockopt(2)), and prints a readable description of these records. When no options are sup- 
plied, trpt prints all the trace records found in the system grouped according to TCP connection 
protocol control block (PCB). 

OPTIONS 

— ■ Print a detailed description of the packet sequencing information, in addition to the nor- 

mal output. 

— t Print the values for all timers at each point in the trace, in addition to the normal out- 

put. 

-J Just give a list of the protocol control block addresses for which there are trace records. 

-pkex-addreee 

Show only trace records associated with the protocol control block who's address follows. 

-a in addition to the normal output, print the values of the source and destination addresses 

for each packet recorded. 

The recommended use of trpt is as follows. Isolate the problem and enable debugging on the 
socket(s) involved in the connection. Find the address of the protocol control blocks associated 
with the sockets using the -A option to net8tat{8). Then run trpt with the — p option, supplying 
the associated protocol control block addresses. If there are many sockets using the debugging 
option, the -J option may be useful in checking to see if any trace records are present for the 
socket in question. 

If debugging is being performed on a system or core file other than the default, the last two argu- 
ments may be used to supplant the defaults. 

FILES 

/vmunix 
/dev/kmem 

SEE ALSO 

setsockopt(2), netstat(8) 

DIAGNOSTICS 

'no namelist' when the system image doesn't contain the proper symbols to find the trace buffer; 
others which should be self explanatory. 

BUGS 

Should ako print the data for each input or output, but this is not saved in the race record. 

The output format is inscrutable, and should be described here. 
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NAME 

tunefs - tune up an existing file system 

SYNOPSIS 

/etc/tunefs tuneup- options speciallfUesya 

DESCRIPTION 

Tunefs is designed to change the dynamic parameters of a file system which affect the layout poli- 
cies. The parameters which are to be changed are indicated by the flags given below: 

-u, maxcontig 

This specifies the maximum number of contiguous blocks that will be laid out before forc- 
ing a rotational delay (see -d below). The default value is one, since most device drivers 
require an interrupt per disk transfer. Device drivers that can chain several buffers 
together in a single transfer should set this to the maximum chain length. 

— d rotdelay 

This specifies the expected time (in milliseconds) to service a transfer completion inter- 
rupt and initiate a new transfer on the same disk. It is used to decide how much rota- 
tional spacing to place between successive blocks in a file. 

-e maxbpg 

Thb indicates the maximum number of blocks any single file can allocate out of a 
cylinder group before it is forced to begin allocating blocks from another cylinder group. 
Typically this value is set to about one quarter of the total blocks in a cylinder group. 
The intent is to prevent any single file from using up all the blocks in a single cylinder 
group, thus degrading access times for all files subsequently allocated in that cylinder 
group. The effect of this limit is to cause big files to do long seeks more frequently than 
if they were allowed to allocate all the blocks in a cylinder group before seeking else- 
where. For file systems with exclusively large files, this parameter should be set higher. 

-m minfree 

This value specifies the percentage of space held back from normal users; the minimum 
free space threshold. The default value used is 10%. This value can be set to zero, how- 
ever up to a factor of three in throughput will be lost over the performuice obtained at a 
10% threshold. Note that if the value is raised above the current usage level, users will 
be unable to allocate files until enough files have been deleted to get under the higher 
threshold. 

SEE ALSO 

fs(5), newf&(8), mkfs(8) 

McKusick, Joy, Leffler; "A Fast File System for Unix", Computer Systems Research Group, Dept 
of EECS, Berkeley, CA 94720; TR #7, September 1982. 



BUGS 



This program should work on mounted and active file systems. Because the super-block is not 
kept in the buffer cache, the program will only take effect if it is run on dismounted file systems, 
(if run on the root file system, the system must be rebooted) 
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NAME 

update - periodically update the super block 

SYNOPSIS 

/etc/update 

DESCRIPTION 

Update is a program that executes the sync{2) primitive every 30 seconds. This insures that the 
file system is fairly up to date in case of a crash. This command should not be executed directly, 
but should be executed out of the initialization shell command file. 

SEE ALSO 

sync(2), 8ync(8), init(8) 
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NAME 

u»|clean - uucp spool directory clean-up 

SYNOPSp 

/||iir/lib/uucp/uuclean ( -ppre ] [ -ntime \ [ -m ) 

DESCRIP'^ION 

U^clean scans the spool directory for files with the specified prefix and deletes all those which are 
older than the specified number of hours. 

OPTIONS 

-lljpre Scan for files with pre as the file prefix. Up to 10 -p arguments may be specified. A -p 
without any pre following deletes all files older than the specified time. 

-ntime Files whose age is more than time hours are deleted if the prefix test is satisfied (default 
time is 72 hours). 

-m Send mail to the owner of the file when it is deleted. 

Unclean will typically be started by cron{S). 

FILES 

/usr/lib/uucp directory with commands used by unclean internally 

/usr/lib/uucp/spool spool directory 

SEE ALSO 

uucp(lC), uux(lC) 
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NAME 

uurec - receive processed news articles via mail 

SYNOPSIS 
uurec 

DESCRIPTION 

uurec reads news articles on the standard input sent by 8endnew8(S), decodes them, and gives 
them to inew8{l) for insertion. 

SEE ALap 

inews(l), readnews(l), recnews(8), 8endnews(8), new8check(l) 
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NAME 

vipw - edit the password file 

SYNOPSIS 

/etc/vlpw 

DESCRIPTION 

Vipw edits the password file while setting the appropriate locks, and does any necessary processing 
after the password file is unlocked. If the password file is already being edited, then you will be 
told to try again later. The vi editor will be used unless the environment variable EDITOR indi- 
cates an alternate editor. Vipw perforins a number of consistency checks on the password entry 
for root, and will not allow a password file with a "mangled" root entry to be installed. 

SEE ALSO 

chsh(l), passwd(l), passwd(5), adduser(8) 

FILES 

/etc/ptmp 
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NAME 

vmstat - report virtual memory statbtics 

SYNOPSIS 

vmstat I -fsS ] | interval [ count | ) 

DESCRIPTION 

Vmstat delves into the system and normally reports certain statistics kept about process, virtual 
memory, disk, trap and cpu activity. 

Without options, vmstat displays a one-line summary of the virtual memory activity since the sys- 
tem has been booted. If intervai b specified, vmstat summarizes activity over the last interval 
seconds. If a count is given, the statistics are repeated count times. 

For example, the following command displays a summary of what the system b doing every five 
seconds. Thb is a good choice of printing interval since thb b how often some of the statistics 
are sampled in the system. 



page dbk faults cpu 

de sr xO xl x2 x3 in sy cs us sy id 
01000 4 12 535 91 
6 1 42 153 31 7 40 54 
5 27 103 25 8 26 66 
6 26 76 25 6 27 67 



The fields of vmstat's display are: 

procs Reports the number of processes in each of the three following states: 
r in run queue 

b blocked for resources (i/o, paging, etc.) 

w runnable or short sleeper (< 20 sees) but swapped 

memory Reports on usage of virtual and real memory. Virtual memory is considered active if it 
belongs to processes which are running or have run in the last 20 seconds, 
avm number of active virtual Kbytes 
fre size of the free Ibt in Kbytes 

page Reports information about page faults and paging activity. The information on each of 
the following activities b averaged each five seconds, and given in units per second, 
re page reclaims (simulating reference bits) — but see the -S option for how this 

field is modified, 
at number of attaches — but see the -S option for how thb field is modified, 

pi pages paged in 

po pages paged out 

fr pages freed per second 

de anticipated short term memory shortfall 

sr pages scanned by clock algorithm, per-second 

dbk Reports number of dbk operations per second (thb field is system dependent). For Sun 
systems, four slots are available for up to four drives: "xO" (or "sO" for SCSI dbks), 
"xl", •'x2", and "x3". 

faults Reports trap/interrupt rate averages per second over last 5 seconds, 
in (non clock) device interrupts per second 

sy system calls per second 

cs cpu context switch rate (switches/sec) 
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VMSTAT(8) 



cpu 



OPTIONS 



-S 



FILES 



Gives a breakdown of percentage usage of CPU time, 
us user time for normal and low priority processes 

sy system time 

id cpu idle 

Report on the number of forks and vforks since system startup and the number of pages 
of virtual memory involved in each kind of fork. 

Display the contents of the sum structure, giving the total number of several kinds of 
paging-related events which have occurred since boot. 

Report on swapping rather than paging activity. This option will change two fields in 
vmstaVs "paging" display: rather than the "re" and "at" fields, vmatat will report "si" 
(swap-ins), and "so" (swap-outs). 



/dev/kmem 
/vmunix 
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This document describes the use of the config{S) program to configure and create bootable 
UNIX kernels. It discusses the structure of kernel configuration files, and how to configure ker- 
nels with non-standard hardware configurations. An appendix contains a summary of the rules 
used by the kernel in calculating the size of kernel data structures, and also indicates some of 
the standard kernel size limitations (and how to change them). 

Config is a tool used in building new Sun UNXXf kernel images. It takes a file describing a 
kernel's tunable parameters and hardware support, and generates a collection of files which are 
then used to build a copy of UNIX appropriate to that configuration. Config simplifies kernel 
maintenance by isolating configuration dependencies in a single, easy to understand, file. 

The first division of this document describes building kernels, and the second describes the syn- 
tax of the configuration file. 

Appendix A gives the grammar for config files. Appendix B describes defaulting rules used dur- 
ing the bootstrap process. Appendix C give sample configuration files. A final appendix gives 
the default rules used in calculating sizes for the most important kernel data structures. It also 
lists kernel data structure size limitations and indicates how you can modify these limits. 

If you are planning to write a device-driver for UNIX, consult the Device Driver Manual in the 
Sun System Internals Manual for more information. 

1. Kernel Building Process 



1.1. Quick Summary 

Assuming the kernel source is located in the /sys directory, there are seven steps in building, 
installing and running a new kernel: 

1) Choose a name for your configuration of the system; for example GAIA. Note that — by 
convention — the name should be in all uppercase letters. 

2) In the /«y«/ con/ directory, create the config file for the system and the directory to contain 
the kernel image: 

# cp GENERIC GAIA 

# chmod -f-w GAIA 

# mkdir ../GAIA 



t UNIX is a trademark of Bell Laboratories. 
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3) Edit GAIA to reflect your system, e.g. change the timezone from 8 to 5 (Pacific to Eastern 
time), delete devices and options which you don't need from the description, and add dev- 
ices which you have which are not in the configuration. 

4) Run config: 

# /etc/config GAIA 

5) Build the new kernel: 

# cd ../GAIA 
i^ make depend 
^ make 

... lots of output ... 

6) Install the new kernel and try it out 

# cp vmunix /newvmunix 

# /etc/ halt 

>b newvmunix — s 

7) If the new kernel appears to work, save the old kernel and install the new one in /vmunix. 

# cd / 

^ mv vmunix ovmunix 
=ff mv newvmunix vmunix 

# /etc/ reboot 

Steps 1 and 2 are usually done only once. When a kernel configuration changes, it usually 
suffices to just run config on the modified configuration file, rebuild the source code dependen- 
cies, and remake the kernel.f 

1.2. Creating a Configuration File 

Configuration files normally reside in the subdirectory /sys/conf. A configuration file is most 
easily constructed by copying an existing configuration file and modifying it. This distribution 
contains a GENERIC configuration file which you can edit to suit your particular system 
configuration. 

The configuration file must have the same name as the directory in which the configured kernel 
is to be built. Further, config assumes this directory is located in the parent directory of the 
directory in which it is run. For example, the generic kernel has a configuration file 
/sys/conf/ GENERIC and an accompanying directory named /sys/ GENERIC. In general it is 
unwise to move your configuration directories out of /sys, as most of the kernel code and the 
files created by config use pathnames of the form "../". If you are running out of space on the 
file system where the configuration directories are located, there is a mechanism (for source dis- 
tributions only) for sharing relocatable object files between kernels. This is described later. 

When building your configuration file, be sure to include the items described in section 3. In 
particular, the machine type, cpu type, timezone, system identifier, maximum users, and root 
device must be specified. The specification of the hardware present may take a bit of work. 



t In rare cases invisible configuration dependencies may exist, requiring the kernel to be rebuilt 
from scratch by removing the kernel building directory and starting again from step 2. This will be 
discussed later. 
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particularly if your hardware is configured at non-standard places (for example, device registers 
located at funny places or devices not supported by the kernel). If the devices to be configured 
are not already described in one of the existing configuration files, check the section 4 manual 
pages in the Sun System Interface Manual. For each supported device, the manual page 
synopsis entry gives a sample configuration line. 

Once the configuration file is complete, run it through config and look for any errors. Never use 
a kernel which config has complained about; the results are unpredictable. For the most part, 
config^s error diagnostics are self-explanatory. It may be the case that the line numbers given 
with the error messages are off by one. 

A successful run of config on your configuration file will generate a number of files in the 
configuration directory. These files are: 

• A file to be used by make{l) in compiling and loading the kernel. 

• One file for each possible kernel image for your machine which describes where the root and 
swap devices are located. 

• A collection of header files, one per possible device the kernel supports, which define the 
hardware configured. 

• A file containing the i/o configuration tables used by the kernel during its autoconfiguration 
phase. 

Unless you suspect that there is a bug in config, or are curious about how the kernel's 
autoconfiguration scheme works, you should never have to look at any of these files. 

1.3. Constructing Source Code Dependencies 

When config is done generating the files needed to compile and link your kernel it will terminate 
with a message of the form "Don't forget to run make depend". This is a reminder that you 
should change your working directory to the configuration directory for the kernel just 
configured, and type "make depend" to build the rules used by make to recognize interdepen- 
dencies in the kernel source code. This will insure that any changes to a piece of the kernel 
source code will result in the proper modules being compiled the next time make is run. 

This step is particularly important if your site makes changes to the kernel include files. The 
rules generated specify which source code files are dependent on which include files. Without 
these rules, make will not recognize when it must rebuild modules due to a kernel header file 
being modified. Note that dependency rules created by this step only reflect directly included 
files. That is, if file "a" includes another file "b", which includes yet another, say "c", and then 
"c" is modified, make will not recognize that "a" should be recompiled. It is best to keep 
include file dependencies only one level deep. 

1.4. Building the Kernel 

The makefile constructed by config should allow a new kernel to be rebuilt by simply typing 
"make image- name". For example, if you have named your bootable kernel image "vmunix", 
then "make vmunix" will generate a bootable image named "vmunix". Alternate kernel image 
names are used when the root file system location and/or swapping configuration is done in 
more than one way. The makefile which config creates has entry points for each kernel image 
defined in the configuration file. Thus, if you have configured "vmunix" to be a kernel with the 
root file system on an "xy" device and "ipvmunix" to be a kernel with the root file system on 
an "ip" device, then "make vmunix ipvmunix" will generate binary images for both. 
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Note that the name of a bootable image is dififerent from the system id3ntifier. All bootable 
images are configured for the same devices; only the information about the root file system and 
paging devices differ. 

The last step in the kernel building process is to rearrange certain commonly used symbols in 
the symbol table of the kernel image; the makefile generated by config does this automatically 
for you. This is advantageous for programs such as pa(l) and vmstat{8), which run much faster 
when the symbols they need are located at the front of the symbol table. Remember also that 
programs such as ps and vmstat expect the currently executing kernel to be named "/vmunix". 
If you install a new kernel and name it something other than "/^™^^^ix"> these programs are 
likely to produce incorrect results. 

1.5. Sharing Object Modules 

This is only effective if you have a source distribution. 

If you have many kernels which are all built on a single machine there are at least two 
approaches to saving time in building kernel images. The best way is to have a single kernel 
image which is run on all machines. This is attractive since it minimizes disk space used and 
time required to rebuild kernels after making changes. However, it is often the case that one or 
more systems will require a separately configured kernel image. This may be due to limited 
memory (building a kernel with many unused device drivers wastes core), or to configuration 
requirements (one machine may be a development machine where disk quotas are not needed, 
while another is a production machine where they are), etc. In these cases it is possible for ker- 
nels to share relocatable object modules which are not configuration dependent; most of the 
modules in the directory /sys/sys are of this sort. 

To share object modules, first build a GENERIC kernel. Then, for each kernel, configure as 
before, but before recompiling and linking, type "make links". This will cause the kernel source 
to be searched for source modules which are safe to share between kernels and generate sym- 
bolic links in the current directory to the appropriate object modules in the directory ../GEN- 
ERIC. A shell script, "makelinks" is generated with this request and may be checked for 
correctness. The file sys/conf/ defines contains a list of symbols which we believe are safe to 
ignore when checking the source code for modules which may be shared. Note that this list 
includes the definitions used to conditionally compile in the virtual memory tracing facilities, 
and the trace point support used only rarely. It may be necessary to modify this list to reflect 
local needs. Also, as described previously, interdependencies which are not directly visible in the 
source code are not caught. Thus if you place per-system dependencies in an include file, they 
will not be recognized. 

1.6. Building Profiled Kernels 

This is only efifective if you have a source distribution. 

It is simple to configure a kernel which will automatically collect profiling information as it 
operates. The profiling data may be collected with kgmon{8) and processed with gprof{l) to 
obtain information regarding the kernel's operation. Profiled kernels maintain histograms of the 
program counter as well as the number of invocations of each routine. The gprof{l) command 
will generate a dynamic call graph of the executing kernel and propagate time spent in each 
routine along the arcs of the call graph. 



7 January 1984 



Building Sun Workstation Kernels Kernel Building Process 

To configure a profiled kernel, use the -p option with config. A profiled kernel is about 5-10% 
larger in its text space due to the calls to count the subroutine invocations. When the kernel 
executes, the profiling data is stored in a buffer which is 1.2 times the size of the text space. 
The overhead for running a profiled kernel varies; under normal load we see anywhere from 5- 
25% of the kernel time spent in the profiling code. 

Note that kernels configured for profiling should not be shared as described above unless all the 
other shared kernels are also to be profiled. 

1.7. Configuring Systems without Source 

Object only releases have binaries for standard system modules in the directory /sys/OBJ. 
Using these binaries you can create new configurations and add new device drivers to the kernel. 
The following lines from the GENERIC config file must be in every config file for object-only 
distributions: 

machine sun 

cpu ''SUN2'' 
options "INET" 

pseudo-device inet 
pseudo-device ether 
pseudo-device loop 
controller mbO at nexus ? 

If you include these lines you can make any changes you wish to the configuration file, provided 
you do not configure in more devices of a particular type than are allowed by the distributed 
object code in ..j OBJ. Attempting to do so will not be detected and may cause the kernel to 
appear to work but have only occasional failures. Double check the .h files in ..j OBJ if you 
change the number of devices configured for any standard drivers. 

1.8. Adding New Device Drivers 

New device drivers require entries in the files fays/ sun/ conf.c, / ays/ conf/ files. sun , and possibly 
/ sys/ sun/ swapgeneric.c and sun/ devices. aun. New devices also require one or more new special 
files to be added to the /dev directory. See the Device Driver Manual in the Syatem Internala 
Manual for the Sun UNIX System. 
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2. Configuration File Syntax 

In this section we consider the specific rules used in writing a configuration file. Appendix A 

gives a complete grammar for the input language; use it if you have problems with syntax 

errors. 

A configuration file has three logical parts: 

• configuration parameters global to all kernel images specified in the configuration file, 

• parameters specific to each kernel image to be generated, and 

• device specifications. 

2.1. Global Configuration Parameters 

The global configuration parameters are the type of machine, cpu types, options, timezone, sys- 
tem identifier, and maximum users. Each is specified with a separate line in the configuration 
file. 

machine type 

The system is to run on the machine type specified. No more than one machine type can 
appear in the configuration file. The appropriate line for the sun is machine sun. 

cpu "^ype" 

This system is to run on the cpu type specified. The appropriate line is cpu ''SUN2''. 

options optionlist 

Compile the listed optional code into the system. Options in this list are separated by com- 
mas. Possible options are listed at the top of the generic makefile. A line of the form 
"options FUNNY,HAHA" generates global "#define"s -DFUNNY -DHAHA in the resul- 
tant makefile. An option may be given a value by following its name with "="j then the 
value enclosed in (double) quotes. 

timezone number [ dst [ number ] ] 

Specifies the timezone you are in. This is measured in the number of hours your timezone is 
west of GMT. EST is 5 hours west of GMT, PST is 8. Negative numbers indicate hours 
east of GMT. If you specify dst, the kernel will operate under daylight savings time. An 
optional integer or floating point number may be included to specify a particular daylight 
saving time correction algorithm; the default value is 1, indicating the United States. Other 
values are: 2 (Australian style), 3 (Western European), 4 (Middle European), and 5 (Eastern 
European). See gettimeofday{2) and ctime{3) for more information. 

ident name 

Gives the system identifier - a name for the machine or machines to run this kernel, name 
must be enclosed in double quotes if it contains both letters and numbers. 

maxusers number 

The maximum expected number of simultaneously active users on this kernel is number. 
This number is used to size several kernel data structures. Typical values are 2 for 1 Mega- 
byte memory single-user Sun Workstation, 4 for Sun Workstations with 2 Megabytes, and 8 
for Sun servers. 
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2.2. Kernel Image Parameters 

Multiple bootable images may be specified in a single configuration file. The kernels will have 
the same global configuration parameters and devices, but the location of the root file system 
and other kernel-specific devices may be different. A kernel image is specified with a "config" 
line: 

config kername config-clauses 

The kername field is the name given to the loaded kernel image; the standard kernel image is 
"vmunix". The configuration clauses are one or more specifications indicating where the root 
file system is located, how many paging devices there are and where they go. 

A configuration clause is one of the following 

root [ on ] root- device 

swap [ on ] swap- device [ and swap- device ]* 

dumps [ on ] dump- device 

args [ on ] arg- device 

(the "on" is optional.) Multiple configuration clauses are separated by white space; config 
allows specifications to be continued across multiple lines by beginning the continuation line 
with a tab character. The "root" clause specifies where the root file system is located, the 
"swap" clause indicates swapping and paging area(s), and the "dumps" clause can be used to 
force crash dumps to be taken on a particular device, and the "args" clause can be used to 
specify that argument list processing for execve should be done on a particular disk. 

The device names supplied in the clauses may be fully specified — as a device, unit, and file sys- 
tem partition — or underspecified. If underspecified, config will use builtin rules to select 
default unit numbers and file system partitions. The defaulting rules are dependent on the 
overall system configuration. For example, the swap area need not be specified at all if the root 
device is specified; in this caae the swap area is placed in the "b" partition of the same disk 
where the root file system is located. Appendix B contains a complete list of the defaulting 
rules used in selecting devices. 

The device names are translated to the appropriate major and minor device numbers on a per- 
machine basis. A file, j ays j conf J devices. machine (where "machine" is the machine type 
specified in the configuration file), is used to map a device name to its major block device 
number. The minor device number is calculated using the standard disk partitioning rules. 

If the default mapping of device name to major/minor device number is incorrect for your 
configuration, it can be replaced by an explicit specification of the major/minor device. This is 
done by substituting 

major x minor y 

where the device name would normally be found. For example, 

config vmunix root on major 00 minor 1 

Normally, the areas configured for swap space are sized by the kernel at boot time. If a non- 
standard partition size is to be used for one or more swap areas, this can also be specified. To 
do this, the device name specified for a swap area should have a "size" specification appended. 
For example, 

config vmunix root on xyO swap on xyOb size 12000 

would force swapping to be done in partition "b" of "xyO" and the swap partition size would be 
set to 1200 sectors. A swap area sized larger than the associated disk partition is trimmed to 
the partition size. 
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To create a generic configuration, only the clause "swap generic" should be specified; any extra 
clauses cause an error. Note that if you use the "swap generic" clause, your system 
identification line must read "ident GENERIC". 

2.3. Device Specifications 

Each device attached to a machine must be specified to config so that the system generated will 
know to probe for it during the autoconfiguration process carried out at boot time. Hardware 
specified in the configuration need not actually be present on the machine where the generated 
system is to be run. Only the hardware actually found at boot time will be used by the system. 

A device specification takes one of the following forms: 

controller device-name device-info [ interrupt- spec ] 
device device-name device-info interrupt-apec 
disk device-name device-info 
tape device-name device-info 

A "controller" is a disk or tape controller. A "device" is an autonomous device which connects 
directly to the Multibus. "Disk" and "tape" identify disk drives and tape drives connected to a 
"controller". 

device-name is a standard UNIX device name (see the section 4 pages of the System Interface 
Manual) concatenated with the logical unit number to be assigned the device. The logical unit 
number may be different than the physical unit number indicated on the front of something like 
a disk; the logical unit number is used to refer to the UNIX device, not the physical unit 
number). The device-info clause specifies how the hardware is connected in the interconnection 
hierarchy. On a Sun Workstation, the following specification should be used: 

controller mbO at nexus f 

The remaining interconnections on the Sun Workstation are: 

• a controller may be connected to the Multibus (mbO), 

• a disk or tape is always attached to a controller, and 

• devices may be attached to controllers or to the Multibus. 

For controllers, the control status register must be given explicitly, as well the interrupt priority 
level of the device. The following lines give an example of each of these interconnections: 

controller xycO at mbO csr Oxee40 priority 2 

disk xyO at xycO drive 

device cgO at mbO csr OxeSOOO priority 3 

Certain device drivers require extra information passed to them at boot time to tailor their 
operation to the actual hardware present. For example, the drivers for the terminal multiplex- 
ors need to know which lines are attached to modem lines so that no one will be allowed to use 
them unless a connection is present. For this reason, one last parameter may be specified to a 
device, a flags field. It has the syntax 

flags number 

and is usually placed after the csr specification. The number is passed directly to the associ- 
ated driver. The manual pages in section 4 should be consulted to determine how each driver 
uses this value (if at all). 
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2.4. Pseudo- devices 

A number of drivers and software subsystems are treated like device drivers without any associ- 
ated hardware. To include any of these pieces, a "pseudo-device" specification must be used. A 
specification for a pseudo device takes the form 

pseudo-device device-name [ howmany ] 

Examples of pseudo devices are the pseudo terminal driver (see pty{A)), where the optional 
howmany value indicates the number of pseudo terminals to configure, and the Sun Window 
System (see u;tn(4)). 
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Appendix A. Configuration File Grammar 

The following grammar is a compressed form of the actual yacc{l) grammar used by config to 
parse configuration files. Terminal symbols are shown all in upper case, literals are emboldened; 
optional clauses are enclosed in brackets, "[" and "]"; zero or more instantiations are denoted 
with "*". 

Configuration ::= [ Spec ; ]* 

Spec ::== Config_spec 
I Devicejspec 
I trace 
I /* lambda */ 

/* configuration specifications */ 

Config_spec ::= machine ID 
I cpu ID 

I options Opt_list 
I ident ID 
I System_spec 

I timezone [ - ] NUMBER [ dst [ NUMBER ] ] 
I timezone [ - ] FPNUMBER [ dst [ NUMBER ] ] 
I maxusers NUMBER 

/* system configuration specifications */ 

Systemjspec ::== config ID System_parameter [ System_parameter ]♦ 

System_parameter ::= swapjspec | root_spec | dump_spec | argjspec 

swap_spec ::= swap [ on ] swap_dev [ and swap_dev ]* 

swap_dev ::= dev_spec [ size NUMBER ] 

rootjspec ::= root [ on ] dev_spec 

dump_spec ::= dumps | on ] devjspec 

arg_spec ::= args [ on ] dev_spec 

dev_spec ::= dev_name | major_minor 

major_minor ::= major NUMBER minor NUMBER 

dev_name ::= ID [ NUMBER [ ID ] ] 

/* option specifications */ 

Opt_list ::= Option [ , Option ]* 
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Option ::= ID [ = Opt_value ] 

Opt_value ::= ID | NUMBER 

/* device specifications */ 

Devicejspec ::= device Dev_name Dev_info Int_spec 
I disk Dev_name Dev_info 
I tape Dev_name Dev_info 
I controller Dev_name Dev_info [ Intjspec ] 
I pseudo-device Dev [ NUMBER ] 

Dev_name ::= Dev NUMBER 

Dev ::= uba | mba | ID 

Dev_info ::= Con_info [ Info ]* 

Conjnfo ::= at Dev NUMBER 
I at nexus NUMBER 

Info ::= csp NUMBER 
I drive NUMBER 
I slave NUMBER 
I flags NUMBER 

Int_spec ::= vector ID { ID ]* 
I priority NUMBER 



Lexical Conventions 

The terminal symbols are loosely defined as: 

ID 

One or more alphabetics, either upper or lower case, and underscore, "_". 

NUMBER 

Approximately the C language specification for an integer number. That is, a leading "Ox" 
indicates a hexadecimal value, a leading "0" indicates an octal value, otherwise the number 
is expected to be a decimal value. Hexadecimal numbers may use either upper or lower case 
alphabetics. 

FPNUMBER 

A floating point number without exponent. That is a number of the form "nnn.ddd", 
where the fractional component is optional. 

In special instances a question mark, "?", can be substituted for a "NUMBER" token. This is 
used to effect wildcarding in device interconnection specifications. 

Comments in configuration files are indicated by a "#" character at the beginning of the line; 
the remainder of the line is discarded. 

A specification is interpreted as a continuation of the previous line if the first character of the 
line is tab. 
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Appendix B. Rules for Defaulting System Devices 

Wlien config processes a "config" rule which does not fully specify the location of the root file 
system, paging area(s), device for system dumps, and device for argument list processing it 
applies a set of rules to define those values left unspecified. The following list of rules are used 
in defaulting system devices. 

1) If a root device is not specified, the swap specification must indicate a "generic" system is to 
be built. 

2) If the root device does not specify a unit number, it defaults to unit 0. 

3) If the root device does not include a partition specification, it defaults to the "a" partition. 

4) If no swap area is specified, it defaults to the "b" partition of the root device. 

5) If no device is specified for processing argument lists, the first swap partition is selected. 

6) If no device is chosen for system dumps, the first swap partition is selected (see below to find 
out where dumps are placed within the partition). 

The following table summarizes the default partitions selected when a device specification is 
incomplete, e.g. "hpO". 



Type 


Partition 


root 


"a" 


swap 


"b" 


args 


"b" 


dumps 


"b" 



B.l. Multiple Swap/Paging Areas 

When multiple swap partitions are specified, the system treats the first specified zis a "primary" 
swap area which is always used. The remaining partitions are then interleaved into the paging 
system at the time a swapon (2) system call is made. This is normally done at boot time with a 
call to swapon (8) from the /etc/rc file. 

B.2. System Dunnps 

System dumps are automatically taken after a system crash, provided the device driver for the 
"dumps" device supports this. The dump contains the contents of memory, but not the swap 
areas. Normally the dump device is a disk in which case the information is copied to a location 
near the back of the partition. The dump is placed in the back of the partition because the pri- 
mary swap and dump device are commonly the same device and this allows the system to be 
rebooted without immediately overwriting the saved information. When a dump has occurred, 
the system variable dumpsize is set to a non-zero value indicating the size (in bytes) of the 
dump. The savecore{8) program then copies the information from the dump partition to a file 
in a "crash" directory and also makes a copy of the system which was running at the time of 
the crash (usually /vmunix). 
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Appendix C. Sample Configuration Files 

The following pages present several sample configuration files. 

The following GENERIC configuration file is used to build the release kernel. Lines are inter- 
preted in ^^comments^^. Lines marked ^^mandatory^ must be included in every configuration 
file; lines which describe devices which your system does not have should be deleted when you 
produce your system configuration file. 



# GENERIC SUN 



# 




machine 


sun 


cpu 


"SUN2" 


ident 


GENERIC 



timezone 


8 dst 


max users 


2 


options 


INET 


options 


SYSACCT 



#**Mandatory**# 

#*»Mandatory»*# 

#**Mandatory** If you use "GENERIC as your system identifier, you may use 
the "swap generic" clause in the "config" line below. If you customize the identifier 
to SYS_NAME, you must either include an "options GENERIC" line or specify at least 
the device where your root file system lives in place of "swap generic". For 
example, the "config" line for a standard Sun lOOU might read: 
"config vmunix root on xy".# 

^♦♦Mandatory** Number and "dst" are variable^ 
^♦♦Mandatory** Number may vary# 
#**Mandatory** INET means include Internet code# 
^Optional; include only with pseudo-device sysacct. 
Controls inclusion of code to do process accounting — see aect{2) and accf (5).# 



config 

pseudo-device 
pseu do- device 
pseudo-device 
pseu do- device 
pseu do- device 
pseudo- device 

pseu do- device 
pseudo-device 
pseudo-device 
pseudo-device 
pseudo- device 

pseu do- device 

controller 

controller 

controller 

disk 

disk 

disk 

disk 



vmunix swap generic 



#**Mandatory** Specify root and swap devices# 



pty #Pseudo-tty's. Needed for network or window system. # 

bk #Berknet line discipline for high speed tty input - see 6fc(4).# 

sysacct ^Include only with SYSACCT options clause, above. # 

inet #**Mandatory** Internet code - see tnef (4). # 

ether #ARP code. Must include if using Ethernet — see orp(4).# 

loop #**Mandatory** Software loop back network device driver; 

must include if INET — see /o(4).# 
nd ^Network disk. Needed if server or diskless - see n<f (4).# 

winl28 #Window system. Number indicates max windows. Must include dtop, below# 

dtop4 #Max Screens ('desktops'); required for window system. # 

ms3 ^Max Mice; required for window system - see m«(4).^ 

kb3 #Max Sun keyboards; required if using any Sun keyboard; 

omit if using serial terminal for console. # 
ingres ^Ingres lock device# 

mbO at nexus ? #**Mandatory** Multibus code.# 

ipcO at mbO csr 0x40 priority 2 #lst Interphase controller - see tp(4).# 

ipcl at mbO csr 0x44 priority 2 ^2nd Interphase controller.^ 

ipO at ipcO drive #lst disk on 1st Interphase controller^ 

ipl at ipcO drive 1 l{^2nd disk on 1st Interphase controller^ 

ip2 at ipcl drive #lst disk on 2nd Interphase controller# 

ip3 at ipcl drive 1 #2nd disk on 2nd Interphase controller^ 
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controller 

controller 

disk 

disk 

disk 

disk 

controller 

disk 

disk 

tape 

controller 

disk 

disk 

tape 

device 

device 

device 

device 

device 

device 

device 

device 

device 

device 

device 

device 

device 

device 

controller 

controller 

tape 

tape 

device 

device 

device 

device 

device 

device 

device 

device 

device 



xycO at mbO csr 0xee40 priority 2 

xycl at mbO csr 0xee48 priority 2 

xyO at xycO drive 

xyl at xycO drive 1 

xy2 at xycl drive 

xy3 at xycl drive 1 

scO at mbO csr 0x80000 priority 2 

sdO at scO drive flags 

sdl at scO drive 1 flags 

stO at scO drive 32 flags 1 

scl at mbO csr 0x84000 priority 2 

sd2 at scl drive flags 

sd3 at scl drive 1 flags 

stl at scl drive 32 flags 1 

ropcO at mbO csr OxeeOSOO priority 1 

skyO at mbO csr 0x2000 priority 2 

zsO at mbO csr 0xeec800 flags 3 priority 2 

zsl at mbO csr OxeecOOO flags 3 priority 2 

zs2 at mbO csr 0x80800 flags 3 priority 2 

zs3 at mbO csr 0x81000 flags 3 priority 2 

zs4 at mbO csr 0x84800 flags 3 priority 2 

zs6 at mbO csr 0x86000 flags 3 priority 2 

octO at mbO csr 0x520 flags Oxff priority 4 

mtiO at mbO csr 0x620 flags Oxff priority 4 

ieO at mbO csr 0x88000 priority 3 

ieO at mbO csr 0x8C000 flags 2 priority 3 

ecO at mbO csr OxeOOOO priority 3 

eel at mbO csr 0xe2000 priority 3 

tmO at mbO csr OxaO priority 3 

tml at mbO csr 0xa2 priority 3 

mtO at tmO drive flags 1 

mtl at tml drive flags 1 

arO at mbO csr 0x200 priority 3 

arl at mbO csr 0x208 priority 3 

cgoneO at mbO csr OxeSOOO priority 3 

bwtwoO at mbO csr 0x700000 priority 3 

bwoneO at mbO csr OxcOOOO priority 3 

vpO at mbO csr 0x400 priority 2 

vpcO at mbO csr 0x480 priority 2 

vpcO at mbO csr 0x500 priority 2 

piO at mbO csr 0xee2000 priority 1 



#lst Xylogics controller - see *y(4).# 

^2nd Xylogics controller^ 

#lst disk on 1st Xylogics controller^ 

^2nd disk on 1st Xylogics controller^ 

#lst disk on 2nd Xylogics controller# 

^2nd disk on 2nd Xylogics controller^ 

#lst SCSI controller# 

#lst disk on 1st SCSI controller # 

#2nd disk on 1st SCSI controller# 

#SCSI tape# 

#2nd SCSI controller# 

#lst disk on 2nd SCSI controIler# 

#2nd disk on 2nd SCSI controller# 

#SCSI tape# 

#**Mandatory** Raster Op chip - see rope (4). # 

#Sky Floating Point board.# 

#CPU ports - see 2»(4).# 

^Sun-2 Video Board ports; 

required if using Sun-2 keyboard and mouse.# 
#lst SCSI Board ports.# 
#lst SCSI Board ports.# 
#2nd SCSI Board ports. # 
#2nd SCSI Board ports. # 
#Central Data Octal Card - see oc«(4).# 
#Systech terminal MUX — see mtt(4).# 
#lst Sun-2 Ethernet Controller# 
#2nd Sun-2 Ethernet ControlIer# 
#lst 3COM Ethernet Controller - see ec(4)# 
#2nd 3COM Ethernet Controller# 
#lst TAPEMASTER tape controller - see <m{4).# 
#2nd TAPEMASTER tape controller# 
#lst 1/2" tape drive on 1st controller.^ 
#lst 1/2" tape drive on 2nd controller.^ 
#lst 1/4" tape drive - see ar(4).# 
#2nd 1/4" tape drive.# 
#lst Sun Color Board - see tfj?(4).# 
#lst monochrome Sun-2 monitor. # 
#lst monochrome Sun-1 monitor. # 
#Ikon Versatec Board - see vp(4).# 
#lst Systech Centronics/Versatec Board - see «p<;(4s). 
#2nd Systech Centronics/Versatec Board. # 
^Parallel input. Only used on Sun Models lOOU 

and 150U, for keyboard and mouse. 

Not needed if using terminal for console.# 
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# Diskless Model 100 

# 

machine sun 

cpu ''SUN2'' 

ident "NDIOO" 

timezone 8 dst 

max users 2 

options INET 

config vmunix root on nd 

pseudo-device pty 

pseudo-device inet 

pseudo-device ether 

pseudo-device loop 

pseudo-device nd 

pseudo-device 'Win32 

pseudo-device dtopl 

pseudo-device msl 

pseudo-device kbl 

controller mbO at nexus ? 

device ropcO at mbO csr OxeeOSOO priority 1 

device zsO at mbO csr OxeecSOO flags 3 priority 2 # cpu ports 

device ecO at mbO csr OxeOOOO priority 3 

device bwoneO at mbO csr OxcOOOO priority 3 

device piO at mbO csr Oxee2000 priority 1 
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# 

# Diskless Model 120 

# 

machine sun 

cpu ''SUN2'' 

ident ''ND120'' 

timezone 8 dst 

max users 2 

options INET 



config 



vmunix root on nd 



pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

controller 

device 

device 

device 

device 

device 

device 

device 



pty 

inet 

ether 

loop 

nd 

Win32 

dtopr 

msl 

kbl 

mbO at nexus ? 

ropcO at mbO csr OxeeOSOO priority 1 

skyO at mbO csr 0x2000 priority 2 

zsO at mbO csr OxeecSOO flags 3 priority 2 ^ cpu ports 

zsl at mbO csr OxeecOOO flags 3 priority 2 # video ports 

ecO at mbO csr OxeOOOO priority 3 

ieO at mbO csr 0x88000 priority 3 

bwtwoO at mbO csr 0x700000 priority 3 
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# Model 120 with one SCSI disk and tape 

# 

machine sun 

cpu ''SUN2'' 

ident ''SDST120'' 

timezone 8 dst 

max users 2 

options INET 



config 



vmunix root on sd 



pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

controller 

controller 

disk 

tape 

device 

device 

device 

device 

device 

device 

device 

device 

device 



pty 

inet 

ether 

loop 

Win32 

dtopl 

msl 

kbl 

mbO at nexus ? 

scO at mbO csr 0x80000 priority 2 

sdO at scO drive flags 

stO at scO drive 32 flags 1 

ropcO at mbO csr OxeeOSOO priority 1 

skyO at mbO csr 0x2000 priority 2 

zsO at mbO csr 0xeec800 flags 3 priority 2 # cpu ports 

zsl at mbO csr OxeecOOO flags 3 priority 2 ^ video ports 

zs2 at mbO csr 0x80800 flags 3 priority 2 

zs3 at mbO csr 0x81000 flags 3 priority 2 

ecO at mbO csr OxeOOOO priority 3 

ieO at mbO csr 0x88000 priority 3 

bwtwoO at mbO csr 0x700000 priority 3 
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# 

# Model 100 with one Xylogics disk 

# 

machine sun 

cpu ''SUN2'' 

ident "XYIOO" 

timezone 8 dst 

max users 2 

options INET 



config 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

controller 

controller 

disk 

device 

device 

device 

device 

device 



vmunix root on xy 

pty 

inet 

ether 

loop 

Win32 

dtopl 

msl 

kbl 

mbO at nexus ? 

xycO at mbO csr Oxee40 priority 2 

xyO at xycO drive 

ropcO at mbO csr OxeeOSOO priority 1 

zsO at mbO csr OxeecSOO flags 3 priority 2 # cpu ports 

ecO at mbO csr OxeOOOO priority 3 

bwoneO at mbO csr OxcOOOO priority 3 

piO at mbO csr Oxee2000 priority 1 
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# 

# Model 100 with one Xylogics disk and Archive tape 

# 

machine sun 

cpu ''SUN2" 

ident "XYARIOO" 

timezone 8 dst 

2 



max users 
options 



INET 



config 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

controller 

controller 

disk 

device 

device 

device 

device 

device 

device 



vmunix root on xy 

pty 

inet 

ether 

loop 

Win32 

dtopl 

msl 

kbl 

mbO at nexus ? 

xycO at mbO csr Oxee40 priority 2 

xyO at xycO drive 

ropcO at mbO csr OxeeOSOO priority 1 

zsO at mbO csr OxeecSOO flags 3 priority 2 ^ cpu ports 

ecO at mbO csr OxeOOOO priority 3 

arO at mbO csr 0x200 priority 3 

bwoneO at mbO csr OxcOOOO priority 3 

piO at mbO csr Oxee2000 priority 1 
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# 

j^ Model 150 server with two Xylogics disks and one 1/2" tape 

# 

machine sun 

cpu ''SUN2'' 

ident "XYMTISO" 

timezone 8 dst 

max users 8 

options INET 

options SYSACCT 



config 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

pseudo-device 

controller 

controller 

disk 

disk 

device 

device 

device 

device 

device 

device 

device 

controller 

tape 

device 

device 

device 



vmunix root on xy 

pty 

bk 

sysacct 

inet 

ether 

loop 

nd 

Win32 

dtopl 

msl 

kbl 

mbO at nexus ? 

xycO at mbO csr 0xee40 priority 2 

xyO at xycO drive 

xyl at xycO drive 1 

ropcO at mbO csr OxeeOSOO priority 1 

skyO at mbO csr 0x2000 priority 2 

zsO at mbO csr OxeecSOO flags 3 priority 2 ij^ cpu ports 

mtiO at mbO csr 0x620 flags Oxfif priority 4 

ecO at mbO csr OxeOOOO priority 3 

eel at mbO csr Oxe2000 priority 3 

ieO at mbO csr 0x88000 priority 3 

tmO at mbO csr OxaO priority 3 

mtO at tmO drive flags 1 

cgoneO at mbO csr Oxe8000 priority 3 

bwoneO at mbO csr OxcOOOO priority 3 

piO at mbO csr Oxee2000 priority 1 
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Appendix D. Data Structure Sizing Rules 

Certain kernel data structures are sized at compile time according to the maximum number of 
simultaneous users expected, while others are calculated at boot time based on the physical 
resources present; e.g. memory. This appendix lists both sets of rules and also includes some 
hints on changing built-in limitations on certain data structures. 

D.l. Compile Time Rules 

The file sys/ conf/ param.c contains the definitions of almost all data structures sized at compile 
time. This file is copied into the directory of each configured kernel to allow configuration- 
dependent rules and values to be maintained. The rules implied by its contents are summarized 
below (here MAXUSERS refers to the value defined in the configuration file in the "maxusers" 
rule). 

nproc 

The maximum number of processes which may be running at any time. It is defined to be 
20 + 8 * MAXUSERS and referred to in other calculations as NPROC. 

ntext 

The maximum number of active shared text segments. Defined as 24 -f- MAXUSERS. 

ninode 

The maximum number of files in the file system which may be active at any time. This 
includes files in use by users, as well as directory files being read or written by the system 
and files associated with bound sockets in the UNIX ipc domain. This is defined as 
(NPROC + 16 + MAXUSERS) + 32. 

nfile 

The number of "file table" structures. One file table structure is used for each open, 
unshared, file descriptor. Multiple file descriptors may reference a single file table entry 
when they are created through a dup call, or as the result of a fork. This is defined to be 

16 * (NPROC + 16 + MAXUSERS) / 10 + 32 

ncallout 

The number of "callout" structures. One callout structure is used per internal system event 
handled with a timeout. Timeouts are used for terminal delays, watchdog routines in device 
drivers, protocol timeout processing, etc. This is defined as 16 + NPROC. 

nclist 

The number of "c-list" structures. C-list structures are used in terminal i/o. This is 
defined as 100 + 16 * MAXUSERS. 

nmb clusters 

The maximum number of pages which may be allocated by the network. This is defined as 
256 (a quarter megabyte of memory) in /sys/h/mbuf.h. In practice, the network rarely uses 
this much memory. It starts off by allocating 64 kilobytes of memory, then requesting more 
as required. This value represents an upper bound. 

nquota 

The number of "quota" structures allocated. Quota structures are present only when disc 
quotas are configured in the system. One quota structure is kept per user. This is defined 
to be (MAXUSERS * 9) / 7 -h 3. 
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ndquot 

The number of "dquot" structures allocated. Dquot structures are present only when disc 
quotas are configured in the system. One dquot structure is required per user, per active file 
system quota. That is, when a user manipulates a file on a file system on which quotas are 
enabled, the information regarding the user's quotas on that file system must be in-core. 
This information is cached, so that not all information must be present in-core all the time. 
This is defined as (MAXUSERS * NMOUNT) / 4 4- NPROC, where NMOUNT is the max- 
imum number of mountable file systems. 

D.2. Run-tiine Calculations 

The most important data structure sized at run-time is the file system buJBfer cache. The system 
allocates 10% of each half-megabyte after the first half-megabyte to the cache. Thus on a 1 
Megabyte machine, 50 kilobytes is allocated to the cache, while on a 2 Megabyte machine, 150 
kilobytes is allocated to the cache. In any case, not less than 16 pages of file system buffers is 
allocated. 

The number of buffers to be allocated can be forced to a specific value by patching the kernel 
variable n6«/with adb: 

^ adb -w /vmunix 
nbuHW 0t32 
nbuf : = 20 
$q 

# 

sets the number of buffers to be 32 (decimal) independent of the amount of main memory avail- 
able. Reboot after performing this series. 

D.3. System Size Limitations 

Because the file system block numbers are stored in page table pg_blkno entries, the maximum 
size of a file system is limited to 2*19 1024 byte blocks. Thus no file system can be larger than 
512M bytes. 

The count of mountable file systems is limited to 15. This should be sufficient. If you have 
many disks it makes sense to make some of them single file systems, and the paging areas don't 
count in this total. To increase this, you must change the core-map (only if you have source) 
/ays/h/cmap.h, since there is a 4 bit field used here. The size of the core-map will then expand 
to 16 bytes per 2048 byte page. Don't forget to change MSWAPX and NMOUNT in 
/sys/h/param.h also. 

The mziximum value NOFILE (open files per process limit) can be raised to is 30 because of a 
bit field in the page table entry in / sys/ machine/ pte.h. 
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Fsck - The UNIX File System Check Program 



When a UNIX operating system is brought up, a consistency check of the file systems should 
always be performed. This precautionary measure helps to insure a reliable environment for file 
storage on disk. If an inconsistency is discovered, corrective action must be taken. Fsck runs 
in two modes. Normally it is run non-interactively by the system after a normal boot. When 
running in this mode, it will only make changes to the file system that are known to always be 
correct. If an unexpected inconsistency is found fsck will exit with a non-zero exit status, leav- 
ing the system running single-user. Typically the operator then runs fack interactively. When 
running in this mode, each problem is listed followed by a suggested corrective action. The 
operator must decide whether or not the suggested correction should be made. 

The purpose of this memo is to dispel the mystique surrounding file system inconsistencies. It 
first describes the updating of the file system (the calm before the storm) and then describes file 
system corruption (the storm). Finally, the set of deterministic corrective actions used by fack 
(the Coast Guard to the rescue) is presented. 

1. Overview of the File System 

The file system is discussed in detail in [Mckusick83]; this section gives a brief overview. 

1.1. Superblock 

A file system is described by its super-block. The super- block is built when the file system is 
created (see newfs{S)) and never changes. The super-block contains the basic parameters of the 
file system, such as the number of data blocks it contains and a count of the maximum number 
of files. Because the super-block contains critical data, newfa replicates it to protect against 
catastrophic loss. The default super block always resides at a fixed offset from the beginning of 
the file system's disk partition. The redundant auper blocka are not referenced unless a head 
crash or other hard disk error causes the default super-block to be unusable. The redundant 
blocks are sprinkled throughout the disk partition. 

Within the file system are files. Certain files are distinguished as directories and contain collec- 
tions of pointers to files that may themselves be directories. Every file has a descriptor associ- 
ated with it called an inode. The inode contains information describing ownership of the file, 
time stamps indicating modification and access times for the file, and an array of indices point- 
ing to the data blocks for the file. In this section, we assume that the first 12 blocks of the file 



This document reflects the use of feck with the revised file system organisation implemented in 
release 0.1 of the Sun UNIX operating system. This is a revision of the original paper written by T. 
J. Kowalski. 
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are directly referenced by values stored in the inode structure itselff. The inode structure may 
also contain references to indirect blocks containing further data block indices. In a file system 
with a 4096 byte block size, a singly indirect block contains 1024 further block addresses, a dou- 
bly indirect block contains 1024 addresses of further single indirect blocks, and a triply indirect 
block contains 1024 addresses of further doubly indirect blocks. 

Sun^s block size is 4K; fragment size is IK. 

In order to create files with up to 2t32 bytes, using only two levels of indirection, the minimum 
size of a file system block is 4096 bytes. The size of file system blocks can be any power of two 
greater than or equal to 4096. The block size of the file system is maintained in the supers 
block, so it is possible for file systems of different block sizes to be accessible simultaneously on 
the same system. The block size must be decided when newft creates the file system; the block 
size cannot be subsequently changed without rebuilding the file system. 

1.2. Summary Information 

Associated with the super block is non replicated Bummary information. The summary informar 
tion changes as the file system is modified. The summary information contains the number of 
blocks, fragments, inodes and directories in the file system. 

1.3. Cylinder Groups 

The file system partitions the disk into one or more areas called cylinder groups. A cylinder 
group is comprised of one or more consecutive cylinders on a disk. Each cylinder group includes 
inode slots for files, a block map describing available blocks in the cylinder group, and summary 
information describing the usage of data blocks within the cylinder group. A fixed number of 
inodes is allocated for each cylinder group when the file system is created. The current policy is 
to allocate one inode for each 2048 bytes of disk space; this is expected to be far more inodes 
than will ever be needed. 

All the cylinder group bookkeeping information could be placed at the beginning of each 
cylinder group. However if this approach were used, all the redundant information would be on 
the top platter. A single hardware failure that destroyed the top platter could cause the loss of 
all copies of the redundant super-blocks. Thus the cylinder group bookkeeping information 
begins at a floating offset from the beginning of the cylinder group. The offset for the i> 1 st 
cylinder group is about one track further from the beginning of the cylinder group than it was 
for the tth cylinder group. In this way, the redundant information spirals down into the pack; 
any single track, cylinder, or platter can be lost without losing all copies of the super-blocks. 
Except for the first cylinder group, the space between the beginning of the cylinder group and 
the beginning of the cylinder group information stores data. 

1 .4. Fragments 

To avoid waste in storing small files, the file system space allocator divides a single file system 
block into one or more fragments. The fragmentation of the file system is specified when the 
file system is created; each file system block can be optionally broken into 2, 4, or 8 addressable 
fragments. The lower bound on the size of these fragments is constrained by the disk sector 



tThe actual number may vary from system to system, but is usually in the range 5-13. 
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size; typically 512 bytes is the lower bound on fragment size. The block map associated with 
each cylinder group records the space availability at the fragment level. Aligned fragments are 
examined to determine block availability. 

On a file system with a block size of 4090 bytes and a fragment size of 1024 bytes, a file is 
represented by zero or more 4096 byte blocks of data, and possibly a single fragmented block. 
If a file system block must be fragmented to obtain space for a small amount of data, the 
remainder of the block is made available for allocation to other files. For example, consider an 
11000 byte file stored on a 4096/1024 byte file system. This file uses two full size blocks and a 
3072 byte fragment. If no fragments with at least 3072 bytes are available when the file is 
created, a full size block is split yielding the necessary 3072 byte fragment and an unused 1024 
byte fragment. This remaining fragment can be allocated to another file, as needed. 

1.5. Updates to the File System 

Every working day hundreds of files are created, modified, and removed. Every time a file is 
modified, the operating system performs a series of file system updates. These updates, when 
written on disk, yield a consistent file system. The file system stages all modifications of critical 
information; modification can either be completed or cleanly backed out after a crash. Knowing 
the information that is first written to the file system, deterministic procedures can be 
developed to repair a corrupted file system. To understand this process, the order that the 
update requests were being honored must first be understood. 

When a user program does an operation to change the file system, such as a write, the data to 
be written is copied into an internal in-core buffer in the kernel. Normally, the disk update is 
handled asynchronously; the user process is allowed to proceed even though the data has not 
yet been written to the disk. The data, along with the inode information reflecting the change, 
is eventually written out to disk. The real disk write may not happen until long after the write 
system call has returned. Thus at any given time, the file system, as it resides on the disk, lags 
behind the state of the file system represented by the in-core information. 

The disk information is updated to reflect the in-core information when the bufler is required for 
another use, when a «ync(2) is done (at 30 second intervals) by /etc/update(S), or by manual 
operator intervention with the sync{S) command. If the system is halted without writing out 
the in-core information, the file system on the disk will be in an inconsistent state. 

If all updates are done asynchronously, several serious inconsistencies can arise. One incon- 
sistency is that a block may be claimed by two inodes. Such an inconsistency can occur when 
the system is halted before the pointer to the block in the old inode has been cleared in the 
copy of the old inode on the disk, and after the pointer to the block in the new inode has been 
written out to the copy of the new inode on the disk. Here, there is no deterministic method for 
deciding which inode should really claim the block. A similar problem can arise with a multiply 
claimed inode. 

The problem with asynchronous inode updates can be avoided by doing all inode deallocations 
synchronously. Consequently, inodes and indirect blocks are written to the disk synchronously 
(i.e. the process blocks until the information is really written to disk) when they are being deal- 
located. Similarly inodes are kept consistent by synchronously deleting, adding, or changing 
directory entries. 
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2. Fixing Corrupted File Systems 

A file system can become corrupted in several ways. The most common of these ways are 
improper shutdown procedures and hardware failures. 

File systems may become corrupted during an vndean halt. This happens when proper shut- 
down procedures are not observed, physically write-protecting a mounted file system, or a 
mounted file system is taken off-line. The most common operator procedural failure is forget- 
ting to sync the system before halting the CPU. 

File systems may become further corrupted if proper startup procedures are not observed, e.g., 
not checking a file system for inconsistencies, and not repairing inconsistencies. Allowing a cor- 
rupted file system to be used (and, thus, to be modified further) can be disastrous. 

Any piece of hardware can fail at any time. Failures can be as subtle as a bad block on a disk 
pack, or as blatant as a non-functional disk-controller. 

2.1. Detecting and Correcting Corruption 

Normally fsck is run non-interactively. In this mode it will only fix corruptions that are 
expected to occur from an unclean halt. These actions arc a proper subset of the actions that 
fsck will take when it is running interactively. Throughout this paper we assume that fsck is 
being run interactively, and all possible errors can be encountered. When an inconsistency is 
discovered in this mode, fsck reports the inconsistency for the operator to chose a corrective 
action. 

A quiescent^ file system may be checked for structural integrity by performing consistency 
checks on the redundant data intrinsic to a file system. The redundant data is either read from 
the file system, or computed from other known values. The file system must be in a quiescent 
state when fsck is run, since fsck is a multi-pass program. 

In the following sections, we discuss methods to discover inconsistencies and possible corrective 
actions for the cylinder group blocks, the inodes, the indirect blocks, and the data blocks con- 
taining directory entries. 

2.2. Super-block Checking 

The most commonly corrupted item in a file system is the summary information associated with 
the super-block. The summary information is prone to corruption because it is modified with 
every change to the file system's blocks or inodes, and is usually corrupted after an unclean 
halt. 

The super-block is checked for inconsistencies involving file-system size, number of inodes, free- 
block count, and the free-inode count. The file-system size must be larger than the number of 
blocks used by the super-block and the number of blocks used by the list of inodes. The file- 
system size and layout information are the most critical pieces of information for fsck. While 
there is no way to actually check these sizes, since they are statically determined by newfs , ftck 
can check that these sizes are within reasonable bounds. All other file system checks require 
that these sizes be correct. If fsck detects corruption in the static parameters of the default 
super-block, fsck requests the operator to specify the location of an alternate super-block. 



X I.e., unmounted and not being written on. 
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2.3. Free Block Checking 

Fack checks that all the blocks marked as free in the cylinder group block maps are not claimed 
by any files. When all the blocks have been initially accounted for, fsck checks that the number 
of free blocks plus the number of blocks claimed by the inodes equals the total number of blocks 
in the file system. 

If anything is wrong with the block allocation maps, ftek will rebuild them, based on the list it 
has computed of allocated blocks. 

The summary information associated with the super-block counts the total number of free 
blocks within the file system. Fsck compares this count to the number of free blocks it found 
within the file system. If the two counts do not agree, then fsck replaces the incorrect count in 
the summary information by the actual free-block count. 

The summary information counts the total number of free inodes within the file system. Fsck 
compares this count to the number of free inodes it found within the file system. If the two 
counts do not agree, then fsck replaces the incorrect count in the summary information by the 
actual free-inode count. 



2.4. Checking the Inode State 

An individual inode is not as likely to be corrupted as the allocation information. However, 
because of the great number of active inodes, a few of the inodes are usually corrupted. 

The list of inodes in the file system is checked sequentially starting with inode 2 (inode marks 
unused inodes; inode 1 is saved for future generations) and progressing through the last inode in 
the file system. The state of each inode is checked for inconsistencies involving format and 
type, link count, duplicate blocks, bad blocks, and inode size. 

Each inode contains a mode word. This mode word describes the type and state of the inode. 
Inodes must be one of six types: regular inode, directory inode, symbolic link inode, special 
block inode, special character inode, or socket inode. Inodes may be found in one of three allo- 
cation states: unallocated, allocated, and neither unallocated nor allocated. This last state sug- 
gests an incorrectly formated inode. An inode can get in this state if bad data is written into 
the inode list. The only possible corrective action is for fsck is to clear the inode. 

2.5. Inode Links 

Each inode counts the total number of directory entries linked to the inode. Fsck verifies the 
link count of each inode by starting at the root of the file system, and descending through the 
directory structure. The actual link count for each inode is calculated during the descent. 

If the stored link count is non-zero and the actual link count is zero, then no directory entry 
appears for the inode. If this happens, fsck will place the disconnected file in the lost -t found 
directory. If the stored and actual link counts are non-zero and unequal, a directory entry may 
have been added or removed without the inode being updated. If this happens, fsck replaces 
the incorrect stored link count by the actual link count. 

Each inode contains a list, or pointers to lists (indirect blocks), of all the blocks claimed by the 
inode. Since indirect blocks are owned by an inode, inconsistencies in indirect blocks directly 
affect the inode that owns it. 

Fsck compares each block number claimed by an inode against a list of already allocated blocks. 
If another inode already claims a block number, then the block number is added to a list of 
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duplicate blocks . Otherwise, the list of allocated blocks is updated to include the block number. 

If there are any duplicate blocks, fsck will perform a partial second pass over the inode list to 
find the inode of the duplicated block. The second pass is needed, since without examining the 
files associated with these inodes for correct content, not enough information is available to 
determine which inode is corrupted and should be cleared. If this condition does arise (only 
hardware failure will cause it), then the inode with the earliest modify time is usually incorrect, 
and should be cleared. If this happens, fsck prompts the operator to clear both inodes. The 
operator must decide which one should be kept and which one should be cleared. 

Fsck checks the range of each block number claimed by an inode. If the block number is lower 
than the first data block in the file system, or greater than the last data block, then the block 
number is a bad block number. Many bad blocks in an inode are usually caused by an indirect 
block that was not written to the file system, a condition which can only occur if there has been 
a hardware failure. If an inode contains bad block numbers, fsck prompts the operator to clear 
it. 

2.6. Inode Data Size 

Each inode contains a count of the number of data blocks that it contains. The number of 
actual data blocks is the sum of the allocated data blocks and the indirect blocks. Fsck com- 
putes the actual number of data blocks and compares that block count against the actual 
number of blocks the inode claims. If an inode contains an incorrect count fsck prompts the 
operator to fix it. 

Each inode contains a thirty-two bit size field. The size is the number of data bytes in the file 
associated with the inode. The consistency of the byte size field is roughly checked by comput- 
ing from the size field the maximum number of blocks that should be associated with the inode, 
and comparing that expected block count against the actual number of blocks the inode claims. 

2.7. Checking the Data Associated with an Inode 

An inode can directly or indirectly reference three kinds of data blocks. All referenced blocks 
must be the same kind. The three types of data blocks are: plain data blocks, symbolic link 
data blocks, and directory data blocks. Plain data blocks contain the information stored in a 
file; symbolic link data blocks contain the path name stored in a link. Directory data blocks 
contain directory entries. Fsck can only check the validity of directory data blocks. 

Each directory data block is checked for several types of inconsistencies. These inconsistencies 
include directory inode numbers pointing to unallocated inodes, directory inode numbers that 
are greater than the number of inodes in the file system, incorrect directory inode numbers for 
^'." and ^'..", and directories that are not attached to the file system. If the inode number in a 
directory data block references an unallocated inode, then fsck will remove that directory entry. 
Again, this condition can only arise when there has been a hardware failure. 

If a directory entry inode number references outside the inode list, then fsck will remove that 
directory entry. This condition occurs if bad data is written into a directory data block. 

The directory inode number entry for "." must be the first entry in the directory data block. 
The inode number for '*.'* must reference itself; e.g., it must equal the inode number for the 
directory data block. The directory inode number entry for ".." must be the second entry in 
the directory data block. Its value must equal the inode number for the parent of the directory 
entry (or the inode number of the directory data block if the directory is the root directory). If 
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the directory inode numbers are incorrect, fack will replace them with the correct values. 

2.8. File System Connectivity 

F»ck checks the general connectivity of the file system. If directories are not linked into the file 
system, then fack links the directory back into the file system in the lost -f- found directory. 
This condition only occurs when there has been a hardware failure. 
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Appendix A. Fsck Error Conditions 

A. 1 . Conventions 

Fsck is a multi-pass file system check program. Each file system pass inTokes a different Phase 
of the fsck program. After the initial setup, fsck performs successive Phases over each file sys- 
tem, checking blocks and sizes, path-names, connectivity, reference counts, and the map of free 
blocks, (possibly rebuilding it), and performs some cleanup. 

Normally fsck is run non-interactively to preen the file systems after an unclean halt. While 
preening a file system, it will only fix corruptions that are expected to occur from an unclean 
halt. These actions are a proper subset of the actions that fsck will take when it is running 
interactively. Throughout this appendix many errors have several options that the operator can 
take. When an inconsistency is detected, fsck reports the error condition to the operator. If a 
response is required, fsck prints a prompt message and waits for a response. When preen'ing 
most errors are fatal. For those that are expected, the response taken is noted. This appendix 
explains the meaning of each error condition, the possible responses, and the related error condi- 
tions. 

The error conditions are organized by the Phase of the fsck program in which they can occur. 
The error conditions that may occur in more than one Phase will be discussed in initialization. 

A.2. Initialization 

Before a file system check can be performed, certain tables have to be set up and certain files 
opened. This section concerns itself with the opening of files and the initialization of tables. 
This section lists error conditions resulting from command line options, memory requests, open- 
ing of files, status of files, file system size checks, and creation of the scratch file. All of the ini- 
tialization errors are fatal when the file system is being preen 'ed. 

C option? 

C is not a legal option to fsck; legal options are -b, -y, -n, and -p. Fsck terminates on this 

error condition. See the fsck(S) manual entry for further detail. 

cannot alloc NNN bytes for block map 

cannot alloc NNN bytes for freemap 

cannot alloc NNN bytes for statemap 

cannot alloc NNN bytes for Incntp 

Fsck^s request for memory for its virtual memory tables failed. This should never happen. 

Fsck terminates on this error condition. See a guru. 

Can't open checklist file: F 

The file system checklist file F (usually /etc/fstab) can not be opened for reading. Fsck ter^ 

minates on this error condition. Check access modes of F. 

Can't stat root 

Fsck^s request for statistics about the root directory "/" failed. This should never happen. 

Fsck terminates on this error condition. See a guru. 
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Can't Stat F 

Can't make sense out of name F 

Fsck^s request for statistics about the file system F failed. When running manually, it ignores 

this file system and continues checking the next file system given. Check access modes of F. 

Can't open F 

Fsek^s request attempt to open the file system F failed. When running manually, it ignores this 

file system and continues checking the next file system given. Check access modes of F. 

F: (NO WRITE) 

Either the -n fiag was specified or fsck''s attempt to open the file system F for writing failed. 
When running manually, all the diagnostics are printed out, but no modifications are attempted 
to fix them. 

file is not a block or character device; OK 

You have given fsck a regular file name by mistake. Check the type of the file specified. 

Possible responses to the OK prompt are: 

YES 

Ignore this error condition. 

NO ignore this file system and continues checking the next file system given. 

One of the following messages will appear: 

MAGIC NUMBER WRONG 

NCG OUT OF RANGE 

CPG OUT OF RANGE 

NSECT < 1 

NTRAK < 1 

SPC DOES NOT JIVE w/NTRAK*NSECT 

INODES NOT MULTIPLE OF A BLOCK 

IMPLIES MORE INODE THAN DATA BLOCKS 

NCYL DOES NOT JIVE WITH NCG^CPG 

FPG DOES NOT JIVE WITH CPG & SPC 

SIZE PREPOSTEROUSLY SMALL 

SIZE PREPOSTEROUSLY LARGE 

CGSIZE INCORRECT 

CSSIZE INCORRECT 

and will be followed by the message: 

F: BAD SUPER BLOCK: B 

USE -b OPTION TO FSCK TO SPECIFY LOCATION OF AN ALTERNATE 

SUPER-BLOCK TO SUPPLY NEEDED INFORMATION; SEE f8ck(8). 

The super block has been corrupted. An alternative super block must be selected from among 
those listed by newfs (8) when the file system was created. For file systems with a blocksize less 
than 32K, specifying -b32 is a good first choice. 

CAN NOT SEEK: BLK B (CONTINUE) 

Fsck^s request for moving to a specified block number B in the file system failed. This should 
never happen. See a guru. 
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Possible responses to the CONTINUE prompt are: 

YES 

attempt to continue to run the file system check. Often, however the problem will persist. 
This error condition will not allow a complete check of the file system. A second run of ftck 
should be made to re-check this file system. If the block was part of the virtual memory 
buffer cache, Jack will terminate with the message "Fatal I/O error". 

NO terminate the program. 

CAN NOT READ: BLK B (CONTINUE) 

FscWs request for reading a specified block number B in the file system failed. This should 
never happen. See a guru. 

Possible responses to the CONTINUE prompt are: 

YES 

attempt to continue to run the file system check. Often, however, the problem will persist. 
This error condition will not allow a complete check of the file system. A second run of fsck 
should be made to re-check this file system. If the block was part of the virtual memory 
buffer cache, fack will terminate with the message "Fatal I/O error". 

NO terminate the program. 

CAN NOT WRITE: BLK B (CONTINUE) 

Fsck^s request for writing a specified block number B in the file system failed. The disk is 
write-protected. See a guru. 

Possible responses to the CONTINUE prompt are: 

YES 

attempt to continue to run the file system check. Often, however, the problem will persist. 
This error condition will not allow a complete check of the file system. A second run of fack 
should be made to re-check this file system. If the block was part of the virtual memory 
buffer cache, fsck will terminate with the message "Fatal I/O error". 

NO terminate the program. 

A.3. Phase 1 - Check Blocks and Sizes 

This phase concerns itself with the inode list. This section lists error conditions resulting from 
checking inode types, setting up the zero-link-count table, examining inode block numbers for 
bad or duplicate blocks, checking inode size, and checking inode format. All errors in this phase 
except INCORRECT BLOCK COUNT are fatal if the file system is being preen'ed, 

eg Ci bad magic number The magic number of cylinder group C is wrong. This usually indi- 
cates that the cylinder group maps have been destroyed. When running manually the cylinder 
group is marked as needing to be reconstructed. 

UNKNOWN FILE TYPE 1=/ (CLEAR) The mode word of the inode / indicates that the 
inode is not a special block inode, special character inode, socket inode, regular inode, symbolic 
link, or directory inode. 

Possible responses to the CLEAR prompt are: 
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YES 

de-allocate inode / by zeroing its contents. This will always invoke the UNALLOCATED 
error condition in Phase 2 for each directory entry pointing to this inode. 

NO ignore this error condition. 

LINK COUNT TABLE OVERFLOW (CONTINUE) 

An internal table for fsck containing allocated inodes with a link count of zero has no more 
room. Recompile ftck with a larger value of MAXLNCNT. 

Possible responses to the CONTINUE prompt are: 

YES 

continue with the program. This error condition will not allow a complete check of the file 
system. A second run of fsck should be made to re-check this file system. If another allo- 
cated inode with a zero link count is found, this error condition is repeated. 

NO terminate the program. 

BBADI=/ 

Inode /contains block number B with a number lower than the number of the first data block 
in the file system or greater than the number of the last block in the file system. This error 
condition may invoke the EXCESSIVE BAD BLKS error condition in Phase 1 if inode / has 
too many block numbers outside the file system range. This error condition will always invoke 
the BAD/DUP error condition in Phase 2 and Phase 4. 

EXCESSIVE BAD BLKS 1=/ (CONTINUE) 

There is more than a tolerable number (usually 10) of blocks with a number lower than the 
number of the first data block in the file system or greater than the number of last block in the 
file system associated with inode /. 

Possible responses to the CONTINUE prompt are: 

YES 

ignore the rest of the blocks in this inode and continue checking with the next inode in the 
file system. This error condition will not allow a complete check of the file system. A 
second run of fsck should be made to re-check this file system. 

NO terminate the program. 

5DUPI=/ 

Inode / contains block number B which is already claimed by another inode. This error condi- 
tion may invoke the EXCESSIVE DUP BLKS error condition in Phase 1 if inode / has too 
many block numbers claimed by other inodes. This error condition will always invoke Phase lb 
and the BAD/DUP error condition in Phase 2 and Phase 4. 

EXCESSIVE DUP BLKS 1=/ (CONTINUE) 

There is more than a tolerable number (usually 10) of blocks claimed by other inodes. 

Possible responses to the CONTINUE prompt are: 

YES 

ignore the rest of the blocks in this inode and continue checking with the next inode in the 
file system. This error condition will not allow a complete check of the file system. A 
second run of fsck should be made to re-check this file system. 
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NO terminate the program. 

DUP TABLE OVERFLOW (CONTINUE) 

An internal table in f»ck containing duplicate block numbers has no more room. Recompile 
fick with a larger value of DUPTBLSIZE. 

Possible responses to the CONTINUE prompt are: 

YES 

continue with the program. This error condition will not allow a complete check of the file 
system. A second run of fsck should be made to re-check this file system. If another dupli- 
cate block is found, this error condition will repeat. 

NO terminate the program. 

PARTLU.LY ALLOCATED INODE 1=/ (CLEAR) 

Inode / is neither allocated nor unallocated. 

Possible responses to the CLEAR prompt are: 

YES 

de-allocate inode / by zeroing its contents. 

NO ignore this error condition. 

INCORRECT BLOCK COUNT I=/(X should be Y) (CORRECT) 

The block count for inode I'lsX blocks, but should be Y blocks. When preen Ung the count is 
corrected. 

Possible responses to the CORRECT prompt are: 

YES 

replace the block count of inode /with Y. 

NO ignore this error condition. 

A.4. Phase IB: Rescan for More Dup's 

When a duplicate block is found in the file system, the file system is rescanned to find the inode 
which previously claimed that block. This section lists the error condition when the duplicate 
block is found. 

BDUPI==/ 

Inode / contains block number B that is already claimed by another inode. This error condition 
will always invoke the BAD/DUP error condition in Phase 2. You can determine which inodes 
have overlapping blocks by examining this error condition and the DUP error condition in 
Phase 1. 



A.5. Phase 2 — Check Pathnames 

This phase concerns itself with removing directory entries pointing to error conditioned inodes 
from Phase 1 and Phase lb. This section lists error conditions resulting from root inode mode 
and status, directory inode pointers in range, and directory entries pointing to bad inodes. All 
errors in this phase are fatal if the file system is being preen *ed. 
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ROOT INODE UNALLOCATED. TERMINATING. 

The root inode (usually inode number 2) has no allocate mode bits. This should never happen. 
The program will terminate. 

NAME TOO LONG F 

An excessively long path name has been found. This is usually indicative of loops in the file 
system name space. This can occur if the super user has made circular links to directories. The 
offending links must be removed (by a guru). 

ROOT INODE NOT DIRECTORY (FIX) 

The root inode (usually inode number 2) is not directory inode type. 

Possible responses to the FIX prompt are: 

YES 

replace the root inode's type to be a directory. If the root inode's data blocks are not direc- 
tory blocks, a VERY large number of error conditions will be produced. 

NO terminate the program. 

DUPS/BAD IN ROOT INODE (CONTINUE) 

Phase 1 or Phase lb have found duplicate blocks or bad blocks in the root inode (usually inode 
number 2) for the file system. 

Possible responses to the CONTINUE prompt are: 

YES 

ignore the DUPS/BAD error condition in the root inode and attempt to continue to run 
the file system check. If the root inode is not correct, then this may result in a large 
number of other error conditions. 

NO terminate the program. 

I OUT OF RANGE I=/NAME=F (REMOVE) 

A directory entry F has an inode number / which is greater than the end of the inode list. 

Possible responses to the REMOVE prompt are: 

YES 

the directory entry F is removed. 

NO ignore this error condition. 

UNALLOCATED 1=/ OWNER=(9 MODE=A/ SIZE=5 MTIME=r DIR=F 
(REMOVE) 

A directory entry F has a directory inode /without allocate mode bits. The owner O, mode A/, 
size S, modify time T, and directory name F are printed. 

Possible responses to the REMOVE prompt are: 

YES 

the directory entry F is removed. 

NO ignore this error condition. 

UNALLOCATED 1==/ OWNER=0 MODE»M SIZE=5 MTIME=:r FILE=F 
(REMOVE) 
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A directory entry F has an inode / without allocate mode bits. The owner O, mode M, size 5, 
modify time T, and file name F are printed. 

Possible responses to the REMOVE prompt are: 

YES 

the directory entry F is removed. 

NO ignore this error condition. 

DUP/BAD 1=/ OWNER= O MODE= M SIZB=5 MTIME=» T DIR=F (REMOVE) 

Phase 1 or Phase lb have found duplicate blocks or bad blocks associated with directory entry 
F, directory inode /. The owner O, mode A/, size S, modify time T, and directory name F are 
printed. 

Possible responses to the REMOVE prompt are: 

YES 

the directory entry F is removed. 

NO ignore this error condition. 

DUP/BAD 1=/ OWNER= O MODE= M SIZB^S MTIME= T FILE=F (REMOVE) 

Phase 1 or Phase lb have found duplicate blocks or bad blocks associated with directory entry 
F, inode /. The owner O, mode M, size S, modify time T, and file name F are printed. 

Possible responses to the REMOVE prompt are: 

YES 

the directory entry F is removed. 

NO ignore this error condition. 

A.6. Phase 3 — Check Connectivity 

This phase concerns itself with the directory connectivity seen in Phase 2. This section lists 
error conditions resulting from unreferenced directories, and missing or full hst-h found direc- 
tories. 

DIRECTORY D CORRUPTED (SALVAGE) 

A directory with an inconsistent internal state has been found. This error is fatal if the file sys- 
tem is being preen 'ed. 

Possible responses to the SALVAGE prompt are: 

YES 

throw away all entries up to the next 512-byte boundary. This rather drastic action can 
throw away up to 42 entries, and should be taken only after other recovery efforts have 

failed. 

NO Skip up to the next 512-byte boundary and resume reading, but do not modify the direc- 
tory. 

UNREF DIR 1=/ OWNER= O MODE=M SIZE=s5 MTIME:== T (RECONNECT) 

The directory inode / was not connected to a directory entry when the file system was 
traversed. The owner O, mode M, size S, and modify time T of directory inode / are printed. 
When preen'ing, the directory is reconnected if its size is non-zero, otherwise it is cleared. 
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Possible responses to the RECONNECT prompt arc: 

YES 

reconnect directory inode / to the file system in the directory for lost files (usually 
lost -h found). This may invoke the lost-h found error condition in Phase 3 if there are prob- 
lems connecting directory inode /to loat-h found. This may also invoke the CONNECTED 
error condition in Phase 3 if the link was successful. 

NO ignore this error condition. This will always invoke the UNREF error condition in Phase 4. 

SORRY. NO lost+found DIRECTORY 

There is no lo9t-h found directory in the root directory of the file system; fsck ignores the 
request to link a directory in lost-t found. This will always invoke the UNREF error condition 
in Phase 4. Check access modes of lost-h found. See fsck^S) manual entry for further detail. 
This error is fatal if the file system is being preen'ed. 

SORRY. NO SPACE IN lost+found DIRECTORY 

There is no space to add another entry to the lost -h found directory in the root directory of the 
file system; fsck ignores the request to link a directory in lost+found. This will always invoke 
the UNREF error condition in Phase 4. Clean out unnecessary entries in lost+found or make 
lost+found larger. See fsck{S) manual entry for further detail. This error is fatal if the file sys- 
tem is being preen'ed. 

Dm 1=11 CONNECTED. PARENT WAS 1=12 

This is an advisory message indicating a directory inode /i was successfully connected to the 
lost+found directory. The parent inode 12 of the directory inode II is replaced by the inode 
number of the lost+found directory. 

A.7. Phase 4 - Check Reference Counts 

This phase concerns itself with the link count information seen in Phase 2 and Phase 3. This 
section lists error conditions resulting from unreferenced files, missing or full lost+found direc- 
tory, incorrect link counts for files, directories, symbolic links, or special files, unreferenced files, 
symbolic links, and directories, bad and duplicate blocks in files, symbolic links, and directories, 
and incorrect total free-inode counts. All errors in this phase are correctable if the file system is 
being preen'ed except running out of space in the lost+ found directory. 

UNREF FILE 1=/ OWNER= MODE=M SIZE=5 MTIME= T (RECONNECT) 

Inode /was not connected to a directory entry when the file system was traversed. The owner 
0, mode A/, size S, and modify time T of inode / are printed. When preen'ing the file is cleared 
if either its size or its link count is zero, otherwise it is reconnected. 

Possible responses to the RECONNECT prompt are: 

YES 

reconnect inode /to the file system in the directory for lost files (usually lost+found). This 
may invoke the lost+found error condition in Phase 4 if there are problems connecting 
inode /to lost+found. 

NO ignore this error condition. This will always invoke the CLEAR error condition in Phase 4. 
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(CLEAR) 

The inode mentioned in the immediately previous error condition can not be reconnected. This 

cannot occur if the file system is being preen'ed, since lack of space to reconnect files is a fatal 

error. 

Possible responses to the CLEAR prompt are: 

YES 

de-allocate the inode mentioned in the immediately previous error condition by zeroing its 
contents. 

NO ignore this error condition. 

SORRY. NO lost+found DIRECTORY 

There is no lost -h found directory in the root directory of the file system; ftck ignores the 

request to link a file in lost-h fottnd. This will always invoke the CLEAR error condition in 

Phase 4. Check access modes of lost-h found. This error is fatal if the file system is being 

preen'ed. 

SORRY. NO SPACE IN lost+found DIRECTORY 

There is no space to add another entry to the lost-h found directory in the root directory of the 
file system; fsck ignores the request to link a file in lost-h found. This will always invoke the 
CLEAR error condition in Phase 4. Check size and contents of lost-h found. This error is fatal 
if the file system is being preen'ed. 

LINK COUNT FILE I=/OWNER=0 MODE=M SIZE=5 MTIME= T COUNT^X 
SHOULD BE Y (ADJUST) 

The link count for inode / which is a file, is X but should be Y. The owner 0, mode M, size S, 
and modify time T are printed. When preen'ing the link count is adjusted. 

Possible responses to the ADJUST prompt are: 

YES 

replace the link count of file inode / with Y. 

NO ignore this error condition. 

LINK COUNT DIR 1=/ OWNER=0 MODE^M SIZE=5 MTIME=r COUNT=sX 
SHOULD BE Y (ADJUST) 

The link count for inode / which is a directory, is X but should be Y. The owner 0, mode A/, 
size S, and modify time T of directory inode / are printed. When preen'ing the link count is 
adjusted. 

Possible responses to the ADJUST prompt are: 
YES 

replace the link count of directory inode / with Y. 

NO ignore this error condition. 

LINK COUNT F 1=/ OWNER=0 MODE=sM SIZE^^ MTIME=r COUNT=A' 
SHOULD BE Y (ADJUST) 

The link count for F inode lis X but should be Y. The name F, owner O, mode M, size 5, and 
modify time T are printed. When preen'ing the link count is adjusted. 
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Possible responses to the ADJUST prompt are: 

YES 

replace the link count of inode / with Y. 

NO ignore this error condition. 

UNREF FILE 1=/ OWNER= MODE=sA/ SIZE=5 MTIME= T (CLEAR) 

Inode / which is a file, was not connected to a directory entry when the file system was 
traversed. The owner O, mode A/, size S, and modify time T of inode / are printed. When 
preen'ing, this is a file that was not connected because its size or link count was zero, hence it is 
cleared. 

Possible responses to the CLEAR prompt are: 

YES 

de-allocate inode / by zeroing its contents. 

NO ignore this error condition. 

UNREF Dm 1=/ OWNER= MODE=A/ S1ZE=S MTIME^:: T (CLEAR) 

Inode / which is a directory, was not connected to a directory entry when the file system was 
traversed. The owner O, mode A/, size S, and modify time T of inode / are printed. When 
preen'ing, this is a directory that was not connected because its size or link count was zero, 
hence it is cleared. 

Possible responses to the CLEAR prompt are: 

YES 

de-allocate inode /by zeroing its contents. 

NO ignore this error condition. 

BAD/DUP FILE 1=/ OWNER= MODE=A/ SIZE=5 MTIME= T (CLEAR) 

Phase 1 or Phase lb have found duplicate blocks or bad blocks associated with file inode /. The 
owner O, mode A/, size 5, and modify time T of inode / are printed. This error cannot arise 
when the file system is being preen W, as it would have caused a fatal error earlier. 

Possible responses to the CLEAR prompt are: 

YES 

de-allocate inode / by zeroing its contents. 

NO ignore this error condition. 

BAD/DUP DIR 1=/ OWNER= MODE=M SIZE»5 MTIME= T (CLEAR) 

Phase 1 or Phase lb have found duplicate blocks or bad blocks associated with directory inode 
/. The owner 0, mode M, size S, and modify time T of inode / are printed. This error cannot 
arise when the file system is being preen'ed, as it would have caused a fatal error earlier. 

Possible responses to the CLEAR prompt are: 

YES 

de- alloc ate inode / by zeroing its contents. 

NO ignore this error condition. 

FREE INODE COUNT WRONG IN SUFERBLK (FIX) 

The actual count of the free inodes does not match the count in the super-block of the file 
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system. When preen'ing, the count is fixed. 

Possible responses to the FIX prompt are: 

YES 

replace the count in the super-block by the actual count. 

NO ignore this error condition. 

A.8. Phase 5 - Check Cyl Groups 

This phase concerns itself with the free-block maps. This section lists error conditions resulting 
from allocated blocks in the free-block maps, free blocks missing from free-block maps, and the 
total free-block count incorrect. 

eg C: bad magic number 

The magic number of cylinder group C is wrong. This usually indicates that the cylinder group 
maps have been destroyed. When running manually the cylinder group is marked as needing to 
be reconstructed. This error is fatal if the file system is being preen'ed. 

EXCESSIVE BAD BLKS IN BIT MAPS (CONTINUE) 

An inode contains more than a tolerable number (usually 10) of blocks claimed by other inodes 
or that are out of the legal range for the file system. This error is fatal if the file system is 
being preen'ed. 

Possible responses to the CONTINUE prompt are: 

YES 

ignore the rest of the free-block maps and continue the execution of jick, 

NO terminate the program. 

SUMMARY INFORMATION T BAD 

where T is one or more of: 

(INODE FREE) 

(BLOCK OFFSETS) 

(FRAG SUMMARIES) 

(SUPER BLOCK SUMMARIES) 

The indicated summary information was found to be incorrect. This error condition will always 

invoke the BAD CYLINDER GROUPS condition in Phase 6. When preen'ing, the summary 

information is recomputed. 

XBLK(S) MISSING 

X blocks unused by the file system were not found in the free-block maps. This error condition 
will always invoke the BAD CYLINDER GROUPS condition in Phase 6. When preen 'ing, 
the block maps are rebuilt. 

BAD CYLINDER GROUPS (SALVAGE) 

Phase 5 has found bad blocks in the free-block maps, duplicate blocks in the free-block maps, or 

blocks missing from the file system. When preen'ing, the cylinder groups are reconstructed. 

Possible responses to the SALVAGE prompt are: 
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YES 

replace the actual free-block maps with a new free-block maps. 

NO ignore this error condition. 

FREE BLK COUNT WRONG IN SUPERBLOCK (FIX) 

The actual count of free blocks does not match the count in the super>block of the file system. 
When preen'ing, the counts are fixed. 

Possible responses to the FIX prompt are: 

YES 

replace the count in the super-block by the actual count. 

NO ignore this error condition. 

A.9. Phase 6 - Salvage Cylinder Groups 

This phase concerns itself with the free-block maps reconstruction. No error messages are pro- 
duced. 

A. 10. Cleanup 

Once a file system has been checked, a few cleanup functions are performed. This section lists 
advisory messages about the file system and modify status of the file system. 

V files, W used, X free ( Y frags, Z blocks) 

This is an advisory message indicating that the file system checked contained V files using W 
fragment sized blocks leaving X fragment sized blocks free in the file system. The numbers in 
parenthesis breaks the free count down into Kfree fragments and Zfree full sized blocks. 

**«** REBOOT UNIX ♦♦•♦* 

This is an advisory message indicating that the root file system has been modified by fsck. If 
UNIX is not rebooted immediately, the work done by fack may be undone by the in-core copies 
of tables UNIX keeps. When preen'ing, ftck will exit with a code of 4. The auto-reboot script 
interprets an exit code of 4 by issuing a reboot system call. 

***** FILE SYSTEM WAS MODIFIED ♦♦♦•♦ 

This is an advisory message indicating that the current file system was modified by fsck. If this 
file system is mounted or is the current root file system, fsck should be halted and UNIX 
rebooted. If UNIX is not rebooted immediately, the work done by fsck may be undone by the 
in-core copies of tables UNIX keeps. 
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ABSTRACT 

Routing mail through a heterogenous internet presents many new problems. Among the 
worst of these is that of address mapping. Historically, this has been handled on an ad 
hoc basis. However, this approach has become unmanageable as internets grow. 

Sendmail acts a unified "post office" to which all mail can be submitted. Address in- 
terpretation is controlled by a production system, which can parse both domain-based 
addressing and old-style ad hoc addresses. The production system is powerful enough to 
rewrite addresses in the message header to conform to the standards of a number of com- 
mon target networks, including old (NCP/RFC733) Arpanet, new (TCP/RFC822) Ar- 
panet, UUCP, and Phonenet. Sendmail also implements an SMTP server, message 
queueing, and aliasing. 



Sendmail implements a general internetwork mail routing facility, featuring aliasing and for- 
warding, automatic routing to network gateways, and flexible configuration. 

In a simple network, each node has an address, and resources can be identified with a host- 
resource pair; in particular, the mail system can refer to users using a host-username pair. Host 
names and numbers have to be administered by a central authority, but usernames can be 
assigned locally to each host. 

In an internet, multiple networks with different characterstics uid managements must com- 
municate. In particular, the syntax and semantics of resource identification change. Certain spe- 
cial cases can be handled trivially by ad hoc techniques, such as providing network names that 
appear local to hosts on other networks, as with the Ethernet at Xerox PARC. However, the 
general case is extremely complex. For example, some networks require point-to-point routing, 
which simplifies the database update problem since only adjacent hosts must be entered into the 
system tables, while others use end-to-end addressing. Some networks use a left-associative syn- 
tax and others use a right-associative syntax, causing ambiguity in mixed addresses. 

Internet standards seek to eliminate these problems. Initially, these proposed expanding the 
address pairs to address triples, consisting of {network, host, resource} triples. Network numbers 
must be universally agreed upon, and hosts can be assigned locally on each network. The user- 
level presentation was quickly expanded to address domains, comprised of a local resource 
identification and a hierarchical domain specification with a common static root. The domain 
technique separates the issue of physical versus logical addressing. For example, an address of the 
form "eric®a.cc.berkeley.arpa" describes only the logical organization of the address space. 

Sendmail is intended to help bridge the gap between the totally ad hoc world of networks 
that know nothing of each other and the clean, tightly-coupled world of unique network numbers. 
It can accept old arbitrary address syntaxes, resolving ambiguities using heuristics specified by the 



fA considerable part of this work was done while nnder the employ of the INGRES Project at the Univeraity of 
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system administrator, as well as domain-based addressing. It helps guide the conversion of mes- 
sage formats between disparate networks. In short, eendmail is designed to assist a graceful tran- 
sition to consistent internetwork addressing schemes. 

Section 1 discusses the design goals for aendmail. Section 2 gives an overview of the basic 
functions of the system. In section 3, detaik of usage are discussed. Section 4 compares sendmaU 
to other internet mail routers, and an evaluation of aendmail is given in section 5, including future 
plans. 

1. DESIGN GOALS 

Design goals for eendmail include: 

(1) Compatibility with the existing mail programs, including Bell version 6 mail, Bell ver- 
sion 7 mail [UNIX83], Berkeley Mail |Shoens79], BerkNet mail (Schmidt79|, and hope- 
fully UUCP mail (Nowitz78a, Nowitz78b]. ARPANET mail (Crocker77a, Po6tel77] was 
also required. 

(2) Reliability, in the sense of guaranteeing that every message is correctly delivered or at 
least brought to the attention of a human for correct disposal; no message should ever be 
completely lost. This goal was considered essential because of the emphasis on mail in 
our environment. It has turned out to be one of the hardest goals to satisfy, especially 
in the face of the many anomalous message formats produced by various ARPANET 
sites. For example, certain sites generate improperly formated addresses, occasionally 
causing error-message loops. Some hosts use blanks in names, causing problems with 
UNIX mail programs that assume that an address is one word. The semantics of some 
fields are interpreted slightly differently by different sites. In summary, the obscure 
features of the ARPANET mail protocol really are used and are difiRcult to support, but 
must be supported. 

(3) Existing software to do actual delivery should be used whenever possible. This goal 
derives as much from political and practical considerations as technical. 

(4) Easy expansion to fairly complex environments, including multiple connections to a sin- 
gle network type (such as with multiple UUCP or Ether nets [Metcalfe76]). This goal 
requires consideration of the contents of an address as well as its syntax in order to 
determine which gateway to use. For example, the ARPANET is bringing up the TCP 
protocol to replace the old NCP protocol. No host at Berkeley runs both TCP and 
NCP, so it is necessary to look at the ARPANET host name to determine whether to 
route mail to an NCP gateway or a TCP gateway. 

(5) Configuration should not be compiled into the code. A single compiled program should 
be able to run as is at any site (barring such basic changes as the CPU type or the 
operating system). We have found this seemingly unimportant goal to be critical in real 
life. Besides the simple problems that occur when any program gets recompiled in a 
different environment, many sites like to "fiddle" with anything that they will be recom- 
piling anyway, 

(6) Sendmail must be able to let various groups maintain their own mailing lists, and let 
individuals specify their own forwarding, without modifying the system alias file. 

(7) Each user should be able to specify which mailer to execute to process mail being 
delivered for him. This feature allows users who are using specialized mailers that use a 
different format to build their environment without changing the system, and facilitates 
specialized functions (such as returning an "I am on vacation" message). 

(8) Network traffic should be minimized by batching addresses to a single host where possi- 
ble, without assistance from the user. 

These goak motivated the architecture illustrated in Figure 1. The user interacts with a 
mail generating and sending prc^ram. When the mail is created, the generator calls eendmail^ 
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Figure 1 - Sendmail System Structure. 



which routes the message to the correct mailer(s). Since some of the senders may be network 
servers and some of the mailers may be network clients, sendmail may be used as an internet 
mail gateway. 

2. OVERVIEW 

2.1. System Organisation 

Sendmail neither interfaces with the user nor does actual mail delivery. Rather, it 
collects a message generated by a user interface program (UIP) such as Berkeley Mail, MS 
|Crocker77b|, or MH [BordenTO], edits the message as required by the destination network, 
and calls appropriate mailers to do mail delivery or queueing for network transmission^. 
This discipline allows the insertion of new mailers at minimum cost. In this sense sendmail 
resembles the Message Processing Module (MPM) of |Postel79b| . 

2.2. Interfaces to the Outside World 

There are three ways sendmail can communicate with the outside world, both in 
receiving and in sending mail. These are using the conventional UNIX argument 
vector/return status, speaking SMTP over a pair of UNIX pipes, and speaking SMTP over 
an interprocess(or) channel. 

2.2.1. Argument vector /exit status 

This technique is the standard UNIX method for communicating with the process. 
A list of recipients is sent in the argument vector, and the message body is sent on the 
standard input. Anything that the mailer prints is simply collected and sent back to 
the sender if there were any problems. The exit status from the mailer is collected 
after the message is sent, and a diagnostic is printed if appropriate. 
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2.2.2. SMTP over pipes 

The SMTP protocol [Postel82] can be used to run an interactive lock-step inter- 
face with the mailer. A subprocess is still created, but no recipient addresses are passed 
to the mailer via the argument list. Instead, they are passed one at a time in com- 
mands sent to the processes standard input. Anything appearing on the standard out- 
put must be a reply code in a special format. 

2.2.3. SMTP over an IPC connection 

This technique is similar to the previous technique, except that it uses a 4.2BSD 
IPC channel |UNIX83|. This method is exceptionally flexible in that the mailer need 
not reside on the same machine. It is normally used to connect to a sendmail process 
on another machine. 

2.3. Operational Description 

When a sender wants to send a message, it issues a request to sendmail using one of 
the three methods described above. Sendmail operates in two distinct phases. In the first 
phase, it collects and stores the message. In the second phase, message delivery occurs. If 
there were errors during processing during the second phase, sendmail creates and returns a 
new message describing the error and/or returns an status code telling what went wrong. 

2.3.1. Argument processing and address parsing 

If sendmail is called using one of the two subprocess techniques, the arguments are 
first scanned and option specifications are processed. Recipient addresses are then col- 
lected, either from the command line or from the SMTP RCPT command, and a list of 
recipients is created. Aliases are expanded at this step, including mailing lists. As 
much validation as possible of the addresses is done at this step: syntax is checked, and 
local addresses are verified, but detailed checking of host names and addresses is 
deferred until delivery. Forwarding is also performed as the local addresses are verified. 

Sendmail appends each address to the recipient list after parsing. When a name is 
aliased or forwarded, the old name is retained in the list, and a flag is set that telk the 
delivery phase to ignore this recipient. Thb list is kept free from duplicates, preventing 
alias loops and duplicate messages deliverd to the same recipient, as might occur if a 
person is in two groups. 

2.3.2. Message collection 

Sendmail then collects the message. The message should have a header at the 
beginning. No formatting requirements are imposed on the message except that they 
must be lines of text (in other words, binary data is not allowed). The header is parsed 
and stored in memory, and the body of the message is saved in a temporary file. 

To simplify the program interface, the message is collected even if no addresses 
were valid. The message will be returned with an error. 

2.3.3. Message delivery 

For each unique mailer and host in the recipient list, sendmail calb the appropri- 
ate mailer. Each mailer invocation sends to all users receiving the message on one host. 
Mailers that only accept one recipient at a time are handled properly. 

The message is sent to the mailer using one of the same three interfaces used to 
submit a message to sendmail. Each copy of the message is prepended by a customized 
header. The mailer status code is caught and checked, and a suitable error message 
given as appropriate. The exit code must conform to a system standard or a generic 
message ("Service unavailable") is given. 
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2^.4. Queuelng for retransmbslon 

If the mailer returned am status that indicated that it might be able to handle the 
mail later, sendmail will queue the mail and try again later. 

2.3.5. Return to sender 

If errors occur during processing, aendmail returns the message to the sender for 
retransmission. The letter can be mailed back or written in the file "dead.letter" in the 
sender's home directory^. 

2.4. Message Header Editing 

Certain editing of the message header occurs automatically. Header lines can be 
inserted under control of the configuration file. Some lines can be merged; for example, a 
"From:" line and a "Full-name:" line can be merged under certain circumstances. 

2.5. Configuration File 

Almost all configuration information is read at runtime from an ASCII file, encoding 
macro definitions (defining the value of macros used internally), header declarations (telling 
sendmail the format of header lines that it will process specially, i.e., lines that it will add 
or reformat), mailer definitions (giving information such as the location and characteristics 
of each mailer), and address rewriting rules (a limited production system to rewrite 
addresses which is used to parse and rewrite the addresses). 

To improve performance when reading the configuration file, a memory image can be 
provided. This provides a "compiled" form of the configuration file. 

3. USAGE AND IMPLEMENTATION 

3.1. Arguments 

Arguments may be flags and addresses. Flags set various processing options. Follow- 
ing flag arguments, address arguments may be given, unless we are running in SMTP 
mode. Addresses follow the syntax in RFC822 [Crocker82] for ARPANET address for- 
mats. In brief, the format is: 

(1) Anything in parentheses is thrown away (as a comment). 

(2) Anything in angle brackets ("< >") is preferred over anything else. This rule imple- 
ments the ARPANET standard that addresses of the form 

user name < machine-address > 

will send to the electronic "machine-address" rather than the human "user name." 

(3) Double quotes ( " ) quote phrases; backslashes quote characters. Backslashes are 
more powerful in that they will cause otherwise equivalent phrases to compare 
differently - for example, user and "^user" are equivalent, but \u8er is different from 
either of them. 

Parentheses, angle brackets, and double quotes must be properly balanced and 
nested. The rewriting rules control remaining parsing^ 



^bvioagly, if the site giving the error is not the originating site, the only reasonable option is to mail back to the 
sender. Also, there are many more error disposition options, bat they only effect the error message - the "retam to 
sender" function is always handled in one of these two ways. 

disclaimer Some special processing is done after rewriting local names; see below. 
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3.2. Mail to Files and Programs 

Files and programs are legitimate message recipients. Files provide archival storage 
of messages, useful for project administration and history. Programs are useful as reci- 
pients in a variety of situations, for example, to maintain a public repository of systems 
messages (such as the Berkeley msgg program, or the MARS system {Sattley78]). 

Any address passing through the initial parsing algorithm as a local address (i.e, not 
appearing to be a valid address for another mailer) is scanned for two special cases. If 
prefixed by a vertical bar ("|") the rest of the address is processed as a shell command. If 
the user name begins with a slash mark ("/") ^be name is used as a file name, instead of a 
login name. 

Files that have setuid or setgid bits set but no execute bits set have those bits 
honored if sendmail is running as root. 

3.3. Aliasing, Forwarding, Inclusion 

Sendmail reroutes mail three ways. Aliasing applies system wide. Forwarding allows 
each user to reroute incoming mail destined for that account. Inclusion directs sendmail to 
read a file for a list of addresses, and is normally used in conjunction with aliasing. 

3.3.1. Aliasing 

Aliasing maps names to address lists using a system-wide file. This file is indexed 
to speed access. Only names that parse as local are allowed as aliases; this guarantees a 
unique key (since there are no nicknames for the local host). 

3.3.2. Forwarding 

After aliasing, recipients that are local and valid are checked for the existence of 
a ".forward" file in their home directory. If it exists, the message is not sent to that 
user, but rather to the list of users in that file. Often this Ibt will contain only one 
address, and the feature will be used for network mail forwarding. 

Forwarding also permits a user to specify a private incoming mailer. For exam- 
ple, forwarding to: 

" I /usr/local/newmail myname" 

will use a different incoming mailer. 

3.3.3. Inclusion 

Inclusion is specified in RFC 733 [CrockerTTa] syntax: 

:Include: pathname 

An address of this form reads the file specified by pathname and sends to all users listed 
in that file. 

The intent is not to support direct use of this feature, but rather to use this as a 
subset of aliasing. For example, an alias of the form: 

project: :include:/usr/project/userlist 

is a method of letting a project maintain a mailing list without interaction with the sys- 
tem administration, even if the alias file is protected. 

It is not necessary to rebuild the index on the alias database when a :include: list 
is changed. 

3.4. Message Collection 

Once all recipient addresses are parsed and verified, the message is collected. The 
message comes in two parts: a message header and a message body, separated by a blank 
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line. 

The header is formatted as a series of lines of the form 

field-name: field-value 

Field-value can be split across lines by starting the following lines with a space or a tab. 
Some header fields have special internal meaning, and have appropriate special processing. 
Other headers are simply passed through. Some header fields may be added automatically, 
such as time stamps. 

The body is a series of text lines. It is completely uninterpreted and untouched, 
except that lines beginning with a dot have the dot doubled when transmitted over an 
SMTP channel. This extra dot is stripped by the receiver. 

3.5. Message Delivery 

The send queue is ordered by receiving host before transmission to implement mes- 
sage batching. Each address is marked as it is sent so rescanning the list is safe. An argu- 
ment list is built as the scan proceeds. Mail to files is detected during the scan of the send 
list. The interface to the mailer is performed using one of the techniques described in sec- 
tion 2.2. 

After a connection is established, sendmail makes the per-mailer changes to the 
header and sends the result to the mailer. If any mail is rejected by the mailer, a flag is 
set to invoke the return-to-sender function after all delivery completes. 

3.0. Queued Messages 

If the mailer returns a "temporary failure" exit status, the message is queued. A 
control file is used to describe the recipients to be sent to and various other parameters. 
This control file is formatted as a series of lines, each describing a sender, a recipient, the 
time of submission, or some other salient parameter of the message. The header of the 
message is stored in the control file, so that the associated data file in the queue is just the 
temporary file that was originally collected. 

3.7. Conflguratlon 

Configuration is controlled primarily by a configuration file read at startup. Sendmail 
should not need to be recomplied except 

(1) To change operating systems (V6, V7/32V, 4BSD). 

(2) To remove or insert the DBM (UNIX database) library. 

(3) To change ARPANET reply codes. 

(4) To add headers fields requiring special processing. 

Adding mailers or changing parsing (i.e., rewriting) or routing information does not require 
recompilation. 

If the mail is being sent by a local user, and the file ".mailer' exists in the sender's 
home directory, that file is read as a configuration file after the system configuratioD file. 
The primary use of this feature is to add header lines. 

The configuration file encodes macro definitions, header definitions, mailer definitions, 
rewriting rules, and options. 

3.7.1. Macros 

Macros can be used in three ways. Certain macros transmit unstructured textual 
information into the mail system, such as the name aendmail will use to identify itself 
in error messages. Other macros transmit information from sendmail to the 
configuration file for use in creating other fields (such as argument vectors to mailers): 
the name of the sender, and the host and user of the recipient. Other macros are 
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unused internally, and can be used as shorthand in the configuration file. 

3.7.2. Header declarations 

Header declarations inform aendmail of the format of known header lines. 
Knowledge of a few header lines is built into gendmail, such as the "From:" and 
"Date:" lines. 

Most configured headers will be automatically inserted in the outgoing message if 
they don't exist in the incoming message. Certain headers are suppressed by some 
mailers. 

3.7.3. Mailer declarations 

Mailer declarations tell aendmaU of the various mailers available to it. The 
definition specifies the internal name of the mailer, the pathname of the program to 
call, some fiags associated with the mailer, and an argument vector to be used on the 
call; thb vector is macro-expanded before use. 

3.7.4. Address rewriting rules 

The heart of address parsing in sendmaii is a set of rewriting rules. These are an 
ordered list of pattern-replacement rules, (somewhat like a production system, except 
that order is critical), which are applied to each address. The address is rewritten tex- 
tually until it is either rewritten into a special canonical form (i.e., a (mailer, host, user) 
3-tuple, such as {arpanet, usc-isif, postel} representing the address "postelQusc-isif"), 
or it falls off the end. When a pattern matches, the rule is reapplied until it fails. 

The configuration file also supports the editing of addresses into different formats. 
For example, an address of the form: 

ucsfcglltef 
might be mapped into: 

tef@ucsfcgl.UUCP 
to conform to the domain syntax. Translations can also be done in the other direction. 

3.7.5. Option setting 

There are several options that can be set from the configuration file. These 
include the pathnames of various support files, timeouts, default modes, etc. 

4. COMPARISON WITH OTHER MAILERS 

4.1. Delivermail 

Sendmail is an outgrowth of delivermail. The primary differences are: 

(1) Configuration information is not compiled in. This change simplifies many of the 
problems of moving to other machines. It aJso allows easy debugging of new mailers. 

(2) Address parsing is more flexible. For example, delivermail only supported one gate- 
way to any network, whereas sendmail can be sensitive to host names and reroute to 
different gateways. 

(3) Forwarding and :include: features eliminate the requirement that the system alias file 
be writable by any user (or that an update program be written, or that the system 
administration make all changes). 

(4) Sendmail supports message batching across networks when a message is being sent to 
multiple recipients. 
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(5) A mail queue is provided in sendmail. Mail that cannot be delivered immediately but 
can potentially be delivered later is stored in this queue for a later retry. The queue 
also provides a buffer against system crashes; after the message has been collected it 
may be reliably redelivered even if the system crashes during the initial delivery. 

(6) Sendmail uses the networking support provided by 4.2BSD to provide a direct inter- 
face networks such as the ARPANET and/or Ethernet using SMTP (the Simple Mail 
Transfer Protocol) over a TCP/IP connection. 

4.2. MMDF 

MMDF [Crocker79] spans a wider problem set than sendmail. For example, the 
domain of MMDF includes a "phone network" mailer, whereas aendmaU calls on preexist- 
ing mailers in most cases. 

MMDF and aendmaU both support aliasing, customized mailers, message batching, 
automatic forwarding to gateways, queueing, and retransmission. MMDF supports two* 
stage timeout, which sendmail does not support. 

The configuration for MMDF is compiled into the code^. 

Since MMDF does not consider backwards compatibility as a design goal, the address 
parsing is simpler but much less flexible. 

It is somewhat harder to integrate a new channel^ into MMDF. In particular, MMDF 
must know the location and format of host tables for all channels, and the channel must 
speak a special protocol. This allows MMDF to do additional verification (such as verify- 
ing host names) at submission time. 

MMDF strictly separates the submission and delivery phases. Although sendmail has 
the concept of each of these stages, they are integrated into one program, whereas in 
MMDF they are split into two programs. 

4.3. Message Processing Module 

The Message Processing Module (MPM) discussed by Postel [PostelTQb] matches 
sendmail closely in terms of its basic architecture. However, like MMDF, the MPM 
includes the network interface software as part of its domain. 

MPM also postulates a duplex channel to the receiver, as does MMDF, thus allowing 
simpler handling of errors by the mailer than is possible in sendmail. When a message 
queued by sendmail is sent, any errors must be returned to the sender by the mailer itself. 
Both MPM and MMDF mailers can return an immediate error response, and a single error 
processor can create an appropriate response. 

MPM prefers passing the message as a structured object, with type-length-value 
tuples*. Such a convention requires a much higher degree of cooperation between mailers 
than is required by sendmail. MPM also assumes a universally agreed upon internet name 
space (with each address in the form of a net-host-user tuple), which sendmail does not. 

5. EVALUATIONS AND FUTURE PLANS 

Sendmail is designed to work in a nonhomogeneous environment. Every attempt is made 
to avoid imposing unnecessary constraints on the underlying mailers. This goal has driven 
much of the design. One of the major problems has been the lack of a uniform address space, 
as postulated in |Postel79a| and |Postel79b|. 



'^!>7namic configiiratioo tables are cairentij being considered for MMDF; allowing the installer to select either com- 
piled or dynamic tables. 

^he MMDF equivalent of a $tndmaU "mailer." 

*This is similar to the NBS standard. 
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A nonuniform address space implies that a path will be specified in all addresses, either 
explicitly (as part of the address) or implicitly (as with implied forwarding to gateways). This 
restriction has the unpleasant effect of making replying to messages exceedingly difficult, since 
there is no one "address" for any person, but only a way to get there from wherever you are. 

Interfacing to mail programs that were not initially intended to be ^plied in an internet 
environment has been amazingly successful, and has reduced the job to a manageable task. 

Sendmail has knowledge of a few difficult environments built in. It generates 
ARPANET FTP/SMTP compatible error messages (prepended with three-digit numbers 
[Neigus73, Postel74, Postel82]) as necessary, optionally generates UNDC-stylc "From" lines on 
the front of messages for some mailers, and knows how to parse the same lines on input. Also, 
error handling has an option customized for BerkNet. 

The decision to avoid doing any type of delivery where possible (even, or perhaps espe- 
cially, local delivery) has turned out to be a good idea. Even with local delivery, there are 
issues of the location of the mailbox, the format of the mailbox, the locking protocol used, 
etc., that are best decided by other programs. One surprisingly major annoyance in many 
internet mailers is that the location and format of local mail is built in. The feeling seems to 
be that local mail is so common that it should be efficient. This feeling is not bom out by our 
experience; on the contrary, the location and format of mailboxes seems to vary widely from 
system to system. 

The ability to automatically generate a response to incoming mail (by forwarding mail to 
a program) seems useful ("I am on vacation until late August....") but can create problems 
such as forwarding loops (two people on vacation whose programs send notes back and forth, 
for instance) if these programs are not well written. A program could be written to do stan- 
dard tasks correctly, but this would solve the general case. 

It might be desirable to implement some form of load limiting. I am unaware of any 
mail system that addresses this problem, nor am I aware of any reasonable solution at this 
time. 

The configuration file is currently practically inscrutable; considerable convenience could 
be realized with a higher-level format. 

It seems clear that common protocols will be changing soon to accommodate changing 
requirements and environments. These changes will include modifications to the message 
header (e.g., [NBS80]) or to the body of the message itself (such as for multimedia messages 
[PostelSO]). Experience indicates that these changes should be relatively trivial to integrate 
into the existing system. 

In tightly coupled environments, it would be nice to have a name server such as Grap- 
vine [Birrell82] integrated into the mail system. This would allow a site such as "Berkeley" to 
appear as a single host, rather than as a collection of hosts, and would allow people to move 
transparently among machines without having to change their addresses. Such a facility 
would require an automatically updated database and some method of resolving conflicts. 
Ideally this would be effective even without all hosts being under a single management. How- 
ever, it is not clear whether this feature should be integrated into the aliasing facility or 
should be considered a "value added" feature outside 9 en (fmai/ itself . 

As a more interesting case, the CSNET name server [SolomonSl] provides an facility 
that goes beyond a single tightly-coupled environment. Such a facility would normally exist 
outside of sendmail however. 
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Sendmail implements a general purpose internetwork mail routing facility under the UNIX* 
operating system. It is not tied to any one transport protocol - its function may be likened to a 
crossbar switch, relaying messages from one domain into another. In the process, it can do a lim- 
ited amount of message header editing to put the message into a format that is appropriate for 
the receiving domain. All of this is done under the control of a configuration file. 

Due to the requirements of flexibility for eendmail, the configuration file can seem somewhat 
unapproachable. However, there are only a few basic configurations for most sites, for which 
standard configuration files have been supplied. Most other configurations can be built by adjust- 
ing an existing configuration file incrementally. 

Although sendmail is intended to run without the need for monitoring, it has a number of 
features that may be used to monitor or adjust the operation under unusual circumstances. These 
features are described. 

Section one describes how to do a basic eendmail installation. Section two explains the 
day-to-day information you should know to maintain your mail system. If you have a relatively 
normal site, these two sections should contain sufficient information for you to install sendmail 
and keep it happy. Section three describes some parameters that may be safely tweaked. Section 
four has information regarding the command line arguments. Section five contains the nitty- 
gritty information about the configuration file. This section is for masochists and people who 
must write their own configuration file. The appendices give a brief but detailed explanation of a 
number of features not described in the rest of the paper. 

The references in this paper are actually found in the companion paper Sendmail - An Inter- 
network Mail Router. Read that paper before this one to gain a basic understanding of how the 
pieces fit together. 

1. BASIC INSTALLATION 

There are two basic steps to installing sendmail The hard part is to build the 
configuration table. This is a file that sendmail reads when it starts up that describes the 
mailers it knows about, how to parse addresses, how to rewrite the message header, and the 
settings of various options. Although the configuration table is quite complex, a configuration 
can usually be built by adjusting an existing off-the-shelf configuration. The second part is 
actually doing the installation, i.e., creating the necessary files, etc. 

The remainder of this section will describe the installation of sendmail assuming you can 
use one of the existing configurations and that the standard installation parameters are accept- 
able. All pathnames and examples are given from the root of the sendmail subtree. 
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1.1. Off-The-Shelf Conllgurations 

You can produce your own 9endmaU.ef file by editing the generic configuration file 
provided with this release: /uer/Ub/Bendmail.generie.ef. Procedures are given in the Set- 
ting Up the Mail System section of the System Set-up and Operation chapter. 

1.2. Installation Using the Makelll* 

A makefile exists in the root of the sendmail directory that will do all of these steps 
for a 4.2BSD system. It may have to be slightly tailored for use on other ^stems. 

Before using this makefile, you should already have created your configuration file 
and left it in the file "cf/«i/d/em.cr' where system is the name of your system (i.e., what is 
returned by hostname{l)). If you do not have hostname you can use the declaration 
"UOST=eystem" on the make{l) command line. You should also examine the file 
md/config.m4 and change the m4 macros there to reflect any libraries and compilation flags 
you may need. 

The basic installation procedure is to type: 

make 
make install 

in the root directory of the sendmait distribution. This will make all binaries and install 
them in the standard places. The second make command must be executed as the 
superuser (root). 

1.3. Installation by Hand 

Along with building a configuration file, you will have to install the sendmail startup 
into your UNIX system. If you are doing this installation in conjunction with a regular 
Berkeley UNIX install, these steps will already be complete. Many of these steps will have 
to be executed as the superuser (root). 

1.3.1. /usr/lib/sendmid] 

The binary for sendmait ia located in /usr/lib. 

1.3.2. /usr/lib/sendmail.cf 

The configuration file that you created earlier should be installed in 
/usr/lib/sendmail.cf; see the Setting up the Mail System section in the System Set-up 
and Operation chapter. 

1.3.3. /usr/ucb/newaliases 

If you are running delivermail, it is critical that the newaliases command be 
replaced. This can just be a link to sendmait 

rm -f /usr/ucb/newaliases 

In /usr/Iib/sendmail /usr/ucb/newaliases 

1.3.4. /usr/lib/sendmallxf 

The configuration file must be installed in ( usr/lib . This is described above. 

1.3.5. /usr/spool/mqueue 

The directory /usr/spool/mqueue should be created to hold the mail queue. This 
directory should be mode 777 unless sendmail is run setuid, when mqueue should be 
owned by the sendmail owner and mode 755. 
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1^.6. /usr/Ub/allaset* 

The file ^'/usT/Mb/ihdses" is the master file for qrstem aliases. This file is a sym- 
bolic link to / private/ aliaget, used for clients. 

1.3.7. /utr/Ub/sendmalLfe 

If you intend to install the frozen version of the configuration file (for quick 
startup) you should create the file /u9r/libf9endmail.fc and initialize it. This step may 
be safely skipped. 

cp /dev/null /usr/lib/sendmail.fc 
/usr/Iib/sendmail -bz 

1.3.8. /etc/rc 

It will be necessary to start up the gendmail daemon when your ^stem reboots. 
This daemon performs two functions: it listens on the SMTP socket for connections (to 
receive mail from a remote system) and it processes the queue periodically to insure 
that mail gets delivered when hosts come up. 

Add the following lines to /etc/rc (or / etc/ re. local as ^propriate) in the area 
where it is starting up the daemons: 

if I -f /usr/lib/sendmail ]; then 

(cd /usr/spool/mqueue; rm -f |lnx|f*) 

/usr/lib/sendmail -bd -q30m Sl 

echo -n ' sendmail' >/dev /console 
fi 

The cd and rm commands insure that all lock files have been removed; extraneous lock 
files may be left around if the system goes down in the middle of processing a message. 
The line that actually invokes sendmaU has two fiags: -bd causes it to listen on the 
SMTP port, and -q30m causes it to run the queue every half hour. 

If you are not running a version of UNIX that supports Berkeley TCP/IP, do not 
include the -bd fiag. 

1.3.0. /uBr/Ilb/8endinall.hf 

This is the help file used by the SMTP HELP command. The file is already 
installed in the distribution. 

1.3.10. /uir/lib/sendmal!.at 

If you wish to collect statistics about your mail traffic, create the file 

/usr/lib/sendmail.st: 

cp /dev/null /usr/lib/sendmail.st 
chmod 666 /usr/lib/sendmail.st 

This file does not grow. It is printed with the program aux/maiUtats. 

1.3.11. /u8r/etc/ln.syBlog 

You may want to run the ayalog program (to collect log information about tend- 
mait). This program normally resides in /usr/etc/in.syslog, with support files 
/etc/eyabg.conf zad /etc/ayslog.pid. The file / ete/ tyflog.eonf desciiheB the file(8) that 
sendmail will log in. For a complete description of syslog, see the manual page for 9y$- 
log{S). 
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1.3.12. /usr/ucb/newaUaMt 

If sendmail is invoked as "newaliases," it will simulate the -bl flag (that is, wUl 
rebuild the alias database; see below). This should be a link to /uer/lib/eendmaU. 

2. NORMAL OPERATIONS 

2.1. Quick Configuration Startup 

A fast version of the configuration file may be set up by using the -bi flag: 

/usr/lib/sendmail -bz 

This creates the file /u8r/Ub/8endmaU.fe ("frozen configuration"). This file is an image of 
sendmairs data space after reading in the configuration file. If this file exists, it is used 
instead of /usr/ lib/ 8endmaU.cf.8endmail.fe time sendmaU.cf \b changed. 

The frozen configuration file will be ignored if a -C flag is specified or if sendmail 
detects that it is out of date. However, the heuristics are not strong so this should not be 
trusted. 

2.2. The System Log 

The system log is supported by the 8y8log{S) program. 

2.2.1. Format 

Each line in the system log consists of a timestamp, the name of the machine that 
generated it (for logging from several machines over the ethemet), the word "send- 
mail:", and a message. 

2.2.2. Levels 

If you have 8y8log{S) or an equivalent installed, you will be able to do logging. 
Syslog installation is performed by the 8etup progtam during first-time UNIX installa- 
tion for Sun systems. There is a large amount <^ information that can be logged. The 
log is arranged as a succession of levels. At the lowest level onfy extreme^ strange 
situations are logged. At the highest level, even the most mundane and uninteresting 
events are recorded for posterity. As a convention, log levels under ten are considered 
"useful;" log levek above ten are usually for debugging purposes. 

A complete description of the log levels is given in section 4.3. 

2.3. The Mall Queue 

The mail queue should be processed transparently. However, you may find that 
manual intervention is sometimes necessary. For example, if a major host is down for a 
period of time the queue may become clogged. Although 8endmail ought to recover grace- 
fully when the host comes up, you may find performance unacceptably bad in the mean- 
time. 

2.3.1. Printing the queue 

The contents of the queue can be printed by specifying the — bp flag to aendmaik 

/usr/lib/sendmail -bp 

This will produce a listing of the queue id's, the size of the message, the date the mes- 
sage entered the queue, and the sender and recipients. 

2.3.2. Format of queue files 

All queue files have the form ztAA9999d where AA99999 is the id for this file and 
the z is a type. The types are: 
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d The data file. The message body (excluding the header) is kept in this file. 

1 The lock file. If this file exists, the job is currently being processed, and a queue 
run will not process the file. For that reason, an extraneous //file can cause a job 
to apparently disappear (it will not even time out!). 

n This file is created when an id is being created. It is a separate file to insure that 
no mail can ever be destroyed due to a race condition. It should exist for no more 
than a few milliseconds at any given time. 

q The queue control file. This file contains the information necessary to process the 
job. 

t A temporary file. These are an image of the qf file when it is being rebuilt. It 
should be renamed to a ^^file very quickly. 

x A transcript file, existing during the life of a session showing everything that hap- 
pens during that session. 

The ^file is structured as a series of lines each beginning with a code letter. The 
lines are as follows: 

D The name of the data file. There may only be one of these lines. 

H A header definition. There may be any number of these lines. The order is 
important: they represent the order in the final message. These use the same syn- 
tax as header definitions in the configuration file. 

R A recipient address. This will normally be completely aliased, but is actually 
realiased when the job is processed. There will be one line for each recipient. 

S The sender address. There may only be one of these lines. 

T The job creation time. This is used to compute when to time out the job. 

P The current message priority. This is used to order the queue. Higher numbers 
mean lower priorities. The priority increases as the message sits in the queue. 
The initial priority depends on the message class and the size of the message. 

M A message. This line is printed by using sendmail with the ~bp flag, and is gen- 
erally used to store status information. It can contain any text. 

As an example, the following is a queue file sent to "mckusickQcalder" and 
"wnj": 

DdfA13557 

Seric 

T404261372 

P132 

Rmckusick®calder 

Rwnj 

H?D?date: 23-Oct-82 15:49:32-PDT (Sat) 

H?F?from: eric (Eric Allman) 

H?x?full-name: Eric Allman 

Hsubject: this is an example message 

Hmessage-id: <8209232249.13557@UCBARPA.BERKELEY.ARPA> 

Hreceived: by UCBARPA.BERKELEYj\RPA (3.227 |lO/22/82|) 

id A13557; 23-Oct-82 15:49:32.PDT (Sat) 
Hphone: (415) 548-3211 
HTo: mckusick®calder, wnj 

This shows the name of the data file, the person who sent the message, the submission 
time (in seconds since January 1, 1970), the message priority, the message class, the 
recipients, and the headers for the message. 



Version 4.2 Last Mod 8/20/83 



Sendmall Initallatloii and Operation Guide 



2^.3. Forcing the queue 

Sendmail should run the queue automatical^ at intervab. The algorithm is to 
read and sort the queue, and then to attempt to process all jobs in order. When it 
attempts to run the job, eendmail first checks to see if the iob is locked. If so, it 

ignores the job. 

There is no attempt to insure that only one queue processor exists at any time, 
since there is no guarantee that a job cannot take forever to process. Due to the lock- 
ing algorithm, it is impossible for one job to freeze the queue. However, an uncoopera* 
tive recipient host or a program recipient that never returns can accumulate many 
processes in your system. Unfortunately, there is no way to resolve Uiis without vidai- 
ing the protocol. 

In some cases, you may find that a major host going down for a couple of days 
may create a prohibitively large queue. This will result in tendmail spending an inordi- 
nate amount of time sorting the queue. This situation can be fixed by moving the 
queue to a temporary place and creating a new queue. The old queue can be run later 
when the offending host returns to service. 

To do this, it b acceptable to move the entire queue direct(»y: 

cd /usr /spool 

mv mqueue omqueue; mkdir mqueue; chmod 777 mqueue 

You should then kill the exbting daemon (since it will still be processing in the old 
queue directory) and create a new daemon. 

To run the old mail queue, run the following command: 

/usr/lib/sendmail -oQ/usr/spool/omqueue -q 

The -oQ flag specifies an alternate queue directory and the -q fiag sa^s to just run 
every job in the queue. If you have a tendency toward voyeurbm, you can use the -v 
flag to watch what is going on. 

When the queue is finally emptied, you can remove the directory: 

rmdir /usr/spool/omqueue 

2.4. The Alias Database 

The alias database exists in two forms. One is a text form, maintained in the file 

/usr/ lib/ aliases. The aliases are of the form 

name: namel, name2, ... 

Only local names may be aliased; e.g., 

eric@mit-xx: ericQbcrkeley 

will not have the desired effect. Aliases may be continued by starting any continuation 
lines with a space or a tab. Blank lines and lines beginning with a sharp sign ("#") are 

comments. 

The second form is processed by the dbm{Z) library. This form b in the files 
/usr/ lib/ aliases. dir and / usr / lib/ alias es.pag. Thb b the form that sendmail actually uses 
to resolve aliases. This technique is used to improve performance. 

2.4.1. RebuUdhig the alias database 

The DBM version of the database may be rebuilt explicitly by executing the com- 
mand 

newaliases 

Thb b equivalent to giving sendmail the — bl fiag: 
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/usr/lib/sendmail -bi 

If the "D" option is specified in the conflgaration, »endmail will rebuild the alias 
database automatically if possible when it is out of date. The conditions under which it 
will do this are: 

(1) The DBM version of the database is mode 666. -or— 

(2) Sendmail is running setuid to root. 

Auto-rebuild can be dangerous on heavily loaded machines with large alias files; if it 
might take more than five minutes to rebuild the database, there is a chance that 
several processes will start the rebuild process simultaneously. 

8.4.2. Potential problems 

There are a number of problems that can occur with the alias database. They all 
result from a sendmail process accessing the DBM version while it is onty partially 
built. This can happen under two circumstances: One process accesses the database 
while another process is rebuilding it, or the process rebuilding the database dies (due 
to being killed or a system crash) before completing the rebuild. 

Sendmail has two techniques to try to relieve these problems. First, it ignores 
interrupts while rebuilding the database; this avoids the problem oi someone aborting 
the process leaving a partially rebuilt database. Second, at the end of the rebuild it 
adds an alias of the form 

Q: G 

(which is not normally legal). Before stndmaU will access the database, it checks to 
insure that this entry exists^ It will wait up to five minutes for this entry to ^pear, at 
which point it will force a rebuild itself^. 

2.4.3. List owners 

If an error occurs on sending to a certain address, say 'V, tendmail will look for 
an alias of the form "owner-z" to receive the errors. Thu is typically useful for a mail- 
ing list where the submitter of the list has no control over the maintanence of the list 
itself; in this case the list maintainer would be the owner of the list. For example: 

Unix- wizards: ericGucbarpa, wnjQmonet, nosuchuser, 

samGmatisse 
owner-unix-wizards: ericQucbarpa 

would cause "ericGucbarpa" to get the error that will occur when someone sends to 
unix-wizards due to the inclusion of "nosuchuser" on the list. 

2.5. Per-User Forwarding (.forward Files) 

As an alternative to the alias database, any user may put a file with the name ".for- 
ward" in his or her home directory. If this file exists, sendmaU redirects mail for that user 
to the list of addresses listed in the .forward file. For example, if the home directory for 
user "mckusick" has a .forward file with contents: 

mckusickQernie 
kirk®calder 

then any mail arriving for "mckusick" will be redirected to the specified accounts. 



^The "»" option is reqaired in tke confi^ntioa for ibis actios to occur. This skonld BonnaJly be specified •aless 
7011 are running (/e/tvertnat7 in parallel with $en4maU. 

^ote: the "D" option mast be specified in the confignration file for this operation to occur. 
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5.0. Special Header Llnee 

Several header lines have special interpretations defined by the configuration file. 
Others have interpretations bailt into gendmaU that cannot be changed without changing 
the code. These builtins are described here. 

S.6.1. Return-Reeelpi-Toi 

If this header is sent, a message will be sent to any specified addresses when the 
final delivery is complete, if the mailer has the 1 fiag (local delivery) set in the mailer 
descriptor. 

2.ft.2. Errors-Toi 

If errors occur anywhere during processing, this header will cause error messages 
to go to the listed addresses rather than to the sender. Thu is intended for mailing 
lists. 

2.5.3. Apparently-Tos 

If a message comes in with no recipients listed in the message (in a To:, Cc:, or 
Bcc: line) then Bendmaii will add an "Apparent(y-To:" header line tor any recipients it 
is aware of. This is not put in as a standard recipient line to warn any recipients that 
the list is not complete. 

At least one recipient line is required under RFC 822. 

3. ARGUMENTS 

The complete list of arguments to tendmaU ia described in detail in Appendix A. Some 
important arguments are described here. 

3.1. Queue Interval 

The amount of time between forking a process to run through the queue is defined by 
the -q flag. If you run in mode f or a this can be relatively large, since it will only be 
relevant when a host that was down comes back up. If you run in q mode it should be 
relatively short, since it defines the maximum amount of time that a message may sit in 
the queue. 

3.2. Daemon Mode 

If you allow incoming mail over an IPC connection, you should have a daemon run- 
ning. This should be set by your /ete/re file using the -bd fiag. The -bd fiag and the -q 
flag may be combined in one call: 

/usr/lib/sendmail -bd -q30m 

3.3. Forcing the Queue 

In some cases you may find that the queue has gotten clogged for scnne reason. You 
can force a queue run using the -q fiag (with no value). It is entertaining to use the -v 
fiag (verbose) when this is done to watch what happens: 

/usr/lib/sendmail -q -v 

3.4. Debugging 

There are a fairly large number of debug fiags built into tendmaiL Each debug flag 
has a number and a level, where higher levels means to print out more information. The 
convention is that levels greater than nine are "absurd," because they print out so much 
information that you wouldn't normally want to see them except for debugging that 
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particular piece of code. Debug flags are set uring the -d <^tioD; the syntax is: 

debug-flag: -d debug-list 
debug-list: debug-option [ , debug-option | 
debug-option: debug-range | . debug-level | 
debug-range: integer | integer - integer 
debug-level: integer 

where spaces are for reading ease only. For example, 

-dl2 Set flag 12 to level 1 

-dl2.3 Set flag 12 to level 3 

m13-17 Set flags 3 through 17 to level 1 

-d3-17.4 Set flags 3 through 17 to level 4 

For a complete list of the available debug flags you will have to look at the code (they are 
too dynamic to keep this documentation up to date). 

3.5. Trying a Different Configuration File 

An alternative configuration file can be specified using the -C flag; for example, 

/usr/lib/sendmail -Ctest.cf 

uses the configuration file test.cflnstezd of the default /usr/lib/aendmail.ef. If the -C flag 
has no value it defaults to iendmail.cfuk the current directory. 

3.0. Changing the Values of Options 

Options can be overridden using the -o flag. Fot example, 
/usr/lib/sendmail -oT2m 
sets the T (timeout) option to two minutes for this run only. 

4. TUNING 

There are a number of configuration parameters you may want to change, depending on 
the requirements of your site. Most of these are set using an option in the configuration file. 
For example, the line "OTSd" sets option T to the value "3d" (three days). 

4.1. Timeouts 

All time intervab are set using a scaled syntax. For example, "10m" represents ten 
minutes, whereas "2h30m" represents two and a half hours. The full set of scales is: 

s seconds 

m minutes 

h hours 

d days 

w weeks 

4.1.1. Queue interval 

The argument to the -q flag specifies how often a subdaemon will run the queue. 
This is typically set to between five minutes and one half hour. 

4.1.2. Read timeouts 

It is possible to time out when reading the standard input or when reading from a 
remote SMTP server. Technically, this is not acceptable within the published proto- 
cols. However, it might be appropriate to set it to something large in certain environ- 
ments (such as an hour). This will reduce the chance of large numbers of idle daemons 
piling up on your system. This timeout is set using the r option in the configuration 
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file. 

4.1^. Message timeouts 

After sitting in the queue for a few days, a message will time out. This is to 
insure that at least the sender is aware of the inability to send a message. The timeout 
is typically set to three days. This timeout is set using the T option in the 
configuration file. 

The time of submission is set in the queue, rather than the amount of time left 
until timeout. As a result, you can Audi messages that have been hanging for a short 
period by running the queue with a short message timeout. For example, 

/usr/lib/sendmail -oTld -q 

will run the queue and flush anything that is one day old. 

4.2. Delivery Mode 

There are a number of delivery modes that tendmaii can operate in, set by the "d" 
configuration option. These modes specify how quickly mail will be delivered. Legal 
modes are: 

i deliver interactive^ (synchronous^) 
b deliver in background (asynchronous^) 
q queue only (don't deliver) 

There are tradeoffs. Mode "i" passes the maximum amount of information to the sender, 
but is hardly ever necessary. Mode "q" puts the minimum toad on your machine, but 
means that delivery may be delayed for up to the queue interval. Mode "b" b probably a 
good compromise. However, this mode can cause large numbers of processes if you have a 
mailer that takes a long time to deliver a message. 

4.3. Log Level 

The level of logging can be set for tendmail. The default using a standard 
configuration table is level 9. The levels are as follows: 

No logging. 

1 Major problems only. 

2 Message collections and failed deliveries. 

3 Successful deliveries. 

4 Messages being defered (due to a host being down, etc.). 

5 Normal message queueups. 

6 Unusual but benign incidents, e.g., trying to process a locked queue file. 

9 Log internal queue id to external message id m^pings. This can be useful for trac- 
ing a message as it travels between several hosts. 

12 Several messages that are basicalfy only of interest when debugging. 

16 Verbose information regarding the queue. 

4.4. FUe Modes 

There are a number of files that may have a number <^ modes. The modes depend 
on what functionality you want and the level of security you require. 

4.4.1. To suid or not to suldf 

SendmaU can safely be made setuid to root. At the point where it is about to 
exec (2) a mailer, it checks to see if the userid is zero; if so, it resets the userid and 
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sroupid to a default (set by the u and g options). (This can be overridden by setting 
the S flag to the mailer for mailers that are trusted and mast be called as root.) How- 
ever, this will cause mail processing to be aceonnted (using ia{S)) to root rather than to 
the user sending the mail. 

4.4.2. Tempcraiy flln modes 

The mode of all temporary files that tendmait creates is determined by the F 
option. Reasonable values for this option are 0600 and 0644. If the more permissive 
mode is selected, it will not be necessary to run »endmaii as root at all (even when run- 
ning the queue). 

4.4.3. Should my alias database be wrttablef 

At Sun Microsystems, we have the alias database {/utr/Ub/alioBes*) mode 666. 
There are some dangers inherent in this approach: any user can add him-/her-8elf to 
any list, or can read any other user's mail. However, we have found users to be basi- 
cally trustworthy, and the cost of having a read-on^ database greater than the expense 
of finding and eradicating the rare nasty person. 

5. THE WHOLE SCOOP ON THE CONFIGURATION FILE 

This section describes the configuration file in detail, including hints on how to write one 
of your own if you have to. 

There b one point that should be made clear immediately: the syntax of the 
configuration file is designed to be reasonably easy to parse, since this is done every time iend- 
mail starts up, rather than easy for a human to read ot write. On the "future project" list is 
a configuration-file compiler. 

An overview of the configuration file is given first, fdlowed by details of the semantics. 

5.1. The Syntax 

The configuration file is organized as a series of lines, each of which begins with a sin- 
gle character defining the semantics for the rest of the line. Lines beginning with a space 
or a tab are continuation lines (although the semantics are not well defined in many 
places). Blank lines and lines beginning with a sharp symbol ('#') are comments. 

5.1.1. R and S - rewriting rules 

The core of address parsing are the rewriting rules. These are an ordered produc- 
tion system. Sendmail scans through the set of rewriting rules looking tat a match on 
the left hand side (LHS) of the rule. When a rule matches, the address is replaced by 
the right hand side (RHS) of the rule. 

There are several sets of rewriting rules. Some of the rewriting sets are used 
internally and must have specific semantics. Other rewriting sets do not have 
specifically assigned semantics, and may be referenced by the mailer definitions or by 
other rewriting sets. 

The syntax of these two commands are: 

Sn 

Sets the current ruleset being collected to n. If you begin a ruleset more than cmce it 
deletes the old definition. 

R/A9 rhs commenta 

The fields must be separated by at least one tab character; there may be embedded 
spaces in the fields. The Ihs is a pattern that is applied to the input. If it matches, the 
input is rewritten to the rhf. The commentB are ignored. 
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S.l.t. D - define macro 

Macros are named with a single character. These may be selected from the entire 
ASCII set, but user-defined macros should be selected from the set of upper case letters 
only. Lower case letters and special symbols are used internal^. 

The syntax for macro definitions is: 

Dzval 

where x is the name of the macro and vol is the value it should have. Macros can be 
interpolated in most places using the escape sequence tx. 

5.1^. C and F - define clniiei 

Classes of words may be defined to match on the left hand side of rewriting rules. 
For example a class of all local names for this site might be created so that attempts to 
send to oneself can be eliminated. These can either be defined direct^ in the 
configuration file or read in from another file. Classes may be given names from the set 
of upper case letters. Lower case letters and special characters are reserved for system 
use. 

The syntax is: 

Ccwordl words... 
Fcfile I format | 

The first form defines the class e to match any of the named words. It is permissible to 
split them among multiple lines; for example, the two forms: 

CHmonet ucbmonet 

and 

CHmonet 
CHucbmonet 

are equivalent. The second form reads the elements of the class e from the named file; 
the format is a 8canf{S) pattern that should produce a single string. 

5.1.4. M - define mailer 

Programs and interfaces to mailers are defined in this line. The format is: 

"Mname, [fields value}* 

where name is the name <^ the mailer (used internal^ only) and the "fieldsxname" 
pairs define attributes of the mailer. Fields are: 

Path The pathname of the mailer 

Flags Special fiags for this maikr 

Sender A rewriting set for sender addresses 

Recipient A rewriting set for recipient addresses 

Argv An argument vector to pass to this mailer 

Eol The end-of-line string for this mailer 

Maxsize The maximum message length to this mailer 

Only the first character of the field name is checked. 

5.1.5. H - define header 

The format of the header lines that tendmail inserts into the message are defined 
by the H line. The syntax of this line is: 

H[fmflag8t\hnamei htemplate 

Continuation lines in this spec are reflected directly into the outgdng message. The 
htemplate is macro expanded before insertion into the message. If the mjlagt 
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(surrounded by question marks) are specified, at least one <^ the specified flags must be 
stated in the mailer definition for this header to be automatically output. If one of 
these headers is in the input it is reflected to the output regardless of these flags. 

Some headers have special semantics that will be described below. 

5.1.0. O - set option 

There are a number of "random" options that can be set from a configuration file. 
Options are represented by single characters. The syntax of this line is: 

00 value 

This sets option o to be value. Depending on the option, vcdue may be a string, an 
integer, a boolean (with legal values "t", "T", "f", or "F"; the default is TRUE), or a 
time interval. 

5.1.7. T - define trusted users 

Trusted users are those users who are permitted to override the sender address 
using the -f flag. These typically are "root," "uucp," and "network," but on some 
users it may be convenient to extend this list to include other users, perha4)s to support 
a separate UUCP login for each host. The syntax of this line is: 

Tuserl userS... 

There may be more than one of these lines. 

5.1.8. P - precedence definitions 

Values for the "Precedence:" field may be defined using the P control line. The 
syntax of this field is: 

Pname^num 

When the name is found in a "Precedence:" field, the message class is set to num. 
Higher numbers mean higher precedence. Numbers less than zero have the special prc^ 
perty that error messages will not be returned. The default precedence is zero. For 
example, our list of precedences is: 

Pfirst-class=0 
Pspecial-delivery = 100 
Pjunk=-100 

5.2. The Semantics 

This section describes the semantics of the configuration file. 

5.2.1. Special macros, conditionals 

Macros are interpolated using the construct %x, where z is the name of the macro 
to be interpolated. In particular, lower case letters are reserved to have special seman- 
tics, used to pass information in or out of eendmail, and some special characters are 
reserved to provide conditionals, etc. 

The following macros must be defined to transmit information into gendmail: 

e The SMTP entry message 

J The "official" domain name for this site 

1 The format of the UNIX from line 

n The name of the daemon (for error messages) 
o The set of "operators" in addresses 
q default format of sender address 

The $e macro is printed out when SMTP starts up. The first watd must be the $J 
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macro. The $J macro should b« in RFC821 fwrnat. The $1 and In macros can be con- 
sidered constants except under terrib^ unusual circumstances. The $o macro consists 
of a list of characters which will be considered tokens and which will separate tokens 
when doing parsing. For example, if "r" were in the to macro, then the input 
"address" would be scanned as three tokens: "add," "r," and "ess." Finally, the |q 
macro specifies how an address should appear in a message when it is defaulted. For 
example, on our system these definitions are: 

De$j Sendmail $v ready at $b 

DnMAILER-DAEMON 

DlFrom $g Id 

Do.:%®!'=/ 

DqlglTx (|x)|. 

DjiH.lD 

An acceptable alternative for the |q macro is "|?x|x |.<lg>". These correspimd to 
the following two formats: 

eric®Berkeley (Eric Allman) 
Eric Allman <ericQBerkeley> 

Some macros are defined by gendmail for interpolation into argv's for mailers or 
for other contexts. These macros are: 

a The origination date in Arpanet format 

b The current date in Arpanet format 

c The hop count 

d The date in UNIX (ctime) format 

f The sender (from) address 

g The sender address relative to the recipient 

h The recipient host 

I The queue id 

p Sendmail's pid 

r Protocol used 

■ Sender's host name 

t A numeric representation of the current time 

u The recipient user 

V The version number of tendmail 

w The hostname of this site 

X The full name of the sender 

y The id of the sender's tty 

I The home directory of the recipient 

There are three types of dates that can be used. The |a and lb macros are in 
Arpanet format; la is the time as extracted from the "Date:" line of the message (if 
there was one), and lb is the current date and time (used for postmarks). If no 
"Date:" line is found in the incoming message, la is set to the current time also. The 
Id macro is equivalent to the la macro in UNIX (ctime) format. 

The If macro is the id of the sender as originally determined; when mailing to a 
specific host the |g macro b set to the address of the sender relative to the recipient. 
For example, if I send to "bollardQmatisse" from the machine "ucbarpa" the If macro 
will be "eric" and the |g macro will be "ericQucbarpa." 

The |x macro is set to the full name of the sender. This can be determined in 
several ways. It can be passed as fiag to eendmail. The second choice is the value <tf 
the "Full-name:" line in the header if it exists, and the third choice is the comment 
field of a "From:" line. If all <A these fail, and if the message is being originated 
locally, the full name a looked up in the /etc/passwd file. 
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When sending, the $h, $u, and $i macros get set to the host, oser, and home 
directory (if local) of the recipient. The first two are set from the $Q and $t part of the 
rewriting rules, respectively. 

The $p and $t macros are used to create unique strinp (e.g., for the "Message- 
Id:" field). The $1 macro is set to the queue id on this host; if put into the timestamp 
line it can be extremely useful for tracking messages. The |y macro is set to the id of 
the terminal of the sender (if known); some systems like to put this in the Unix "From" 
line. The $v macro is set to be the version number of tendmaU; this is normally put in 
timestamps and has been proven extremely useful for debugging. The $w macro is set 
to the name of this host if it can be determined. The |e field is set to the "hop count," 
i.e., the number of times this message has been processed. This can be determined by 
the -h flag on the command line or by counting the timestamps in the message. 

The $r and $8 fields are set to the protocol used to communicate with eendmaii 
and the sending hostname; these are not supported in the current version. 

Conditionals cw be specified using the syntax: 

$?x textl $1 text2 $. 

This interpolates textl if the macro $x is set, and textS otherwise. The "eke" (||) 
clause may be omitted. 

5.2.2. Spedal classes 

The class $^w is set to be the set of all names this host is known by. This can 
be used to delete local hostnames. 

5.2.3. The left hand side 

The left hand side of rewriting rules contains a pattern. Normal words are simply 
matched directly. Metasyntax is introduced using a dollar sign. The metasymbols are: 

$• Match zero or more tokens 

$+ Match one or more tokens 

I— Match exactly one token 

$=:z Match any token in class x 

%'x Match any token not in class x 

If any of these match, they are assigned to the symbol $n for replacement on the right 
hand side, where n is the index in the LHS. For example, if the LHS: 

is applied to the input: 

UCBARPA:eric 

the rule will match, and the values passed to the RHS will be: 

$1 UCBARPA 
$2 eric 

5.2.4. The right hand side 

When the right hand side <^ a rewriting rule matches, the input is deleted and 
replaced by the right hand side. Tokens are copied directly from the RHS unless they 
are begin with a dollar sign. Metasymbob are: 
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In Substitute indefinite U^en n from LHS 

$>n "Call" ruleset n 

tifmailer Resolve to mailer 

tiihoat Specify ho»t 

tsu8er Specify user 

The In syntax substitutes the cOTresponding value from a |«f , |~, I*, $mm, or I' 
match on the LHS. It may be used anywhere. 

The |>n syntax causes the remainder of the line to be substituted as usual and 
then passed as the argument to ruleset n. The final value of ruleset n then becomes the 
substitution for this rule. 

The |# syntax should only be used in ruleset zero. It causes evaluation of the 
ruleset to terminate immediately, and signab to eendmaU that the address has com- 
pletely resolved. The complete syntax is: 

|# mailertfihos^tuser 

This specifies the {mailer, host, user} 3-tupk necessary to direct the mailer. If the 
mailer is local the host part may be omitted. The mailer and host must be a nngle 
word, but the user may be multi-part. 

A RHS may also be preceeded by a |0 or a It to control evaluati(m. A |0 prefix 
causes the ruleset to return with the remainder of the RHS as the value. A It prefix 
causes the rule to terminate inunediately, but the ruleset to continue; this can be used 
to avoid continued application of a rule. The prefix is stripped before continuing. 

The |Q and It prefixes may preceed a |> spec; tot example: 

RI+ |:|>7|1 

matches anything, passes that to ruleset seven, and continues; the It is necessary to 
avoid an infinite loop. 

5.2.5. Semantics of rewriting rule sets 

There are five rewriting sets that have specific semantics. These are related as 
depicted by Figure 2. 

Ruleset three should turn the address into "canonical fwm." This form should 
have the basic syntax: 

local-part®host-domain-spec 

If no "3" sign is specified, then the host-domain-spec may be appended from the sender 
address (if the C fiag is set in the mailer definition corresponding to the sending 
mailer). Ruleset three is applied by sendmail before doing anything with any address. 

Ruleset zero is applied after ruleset three to addresses that are going to actually 
specify recipients. It must resolve to a {mailer, host, user} triple. The mailer must be 
defined in the mailer definitions from the configuration file. The host is defined into the 
|h macro for use in the argv expansion of the specified mailer. 

Rttlesets one and two are applied to all sender and recipient addresses respec- 
tively. They are applied before any specification in the mailer definition. They must 
never resolve. 

Ruleset four is applied to all addresses in the message. It is typically used to 
translate internal to external tana. 

5.2.6. Mailer flaga etc. 

There are a number of flags that may be associated with each mailer, each 
identified by a letter of the alphabet. Many of them are assigned semantics internally. 
These are detailed in Appendix C. Any other flags may be used freefy to conditionally 
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Figure 2 - Rewriting Set Semantics 

D - sender domain addition 

S - mailer-specific sender rewriting 

R - mailer-specific recipient rewriting 

assign headers to messages destined for particular mailers. 

5.2.7. The "error" mailer 

The mailer with the special name "error" can be used to generate a user error. 
The (optional) host field is a numeric exit status to be returned, and the user field is a 
message to be printed. For example, the entry: 

$#error$:Host unknown in this domain 

on the RHS of a rule will cause the specified error to be generated if the LHS matches. 
This mailer is only functional in ruleset zero. 

5.3. Building a Configuration File From Scratch 

Building a configuration table from scratch is an extremely di^cult job. Fortunately, 
it is almost never necessary to do so; nearly every situation that may come up may be 
resolved by changing an existing table. In any case, it is critical that you understand what 
it is that you are trying to do and come up with a philosophy for the configuration table. 
This section is intended to explain what the real purpose of a configuration table is and to 
give you some ideas for what your philosophy might be. 

6.3.1. What you are trying to do 

The configuration table has three major purposes. The first and simplest is to set 
up the environment for BendmaiL This involves setting the options, defining a few criti- 
cal macros, etc. Since these are described in other places, we will not go into more 
detail here. 

The second purpose is to rewrite addresses in the message. This should typically 
be done in two phases. The first phase maps addresses in any format into a canonical 
form. This should be done in ruleset three. The second phase maps this canonical form 
into the syntax appropriate for the receiving mailer. Sendmail does this in three sub- 
phases. Rulesets one and two are applied to all sender and recipient addresses respec- 
tively. After this, you may specify per-mailer rulesets for both sender and recipient 
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addresses; this allows mailer-specific cQ8toniicati<». Finally, raleset four is applied to 
do any default conversion to external form. 

The third purpose is to m^ addresses into the actual set of instructions necessary 
to get the message delivered. Ruleset zero must resolve to the internal form, which is 
in turn used as a pointer to a mailer descriptor. The mailer descriptor describes the 
interface requirements of the mailer. 

6.3.2. Philosophy 

The particular philosophy you choose will depend heavily on the size and struc- 
ture of your organization. I will present a few possible philosophies here. 

One general point applies to all of these philosophies: it is almost always a mis- 
take to try to do full name resolution. For example, if you are trying to get names of 
the form "userQhost" to the Arpanet, it does not pay to route them to 
"xyzvax!decvax!ucbvax!c70:userOhost" since yoo then depend on several links not 
under your control. The best approach to this problem is to simply forward to 
"xyzvax!user®ho8t" and let xyzvax worry about it from there. In summary, just get 
the message closer to the destination, rather than determining the full path. 

5.3.2.1. Large site, many hosts - minimum Information 

Berkeley is an example of a large site; it has more than two or three hosts. 
Berkeley has decided that the only reasonable philosophy for their environment is to 
designate one host as site guru. It must be able to resolve any piece of mail it 
receives. The other sites should have the minimum amount of information they can 
get away with, and even this minimum should be hints rather than solid informs^ 
tion. 

For example, a typical site on the Berkeley local ether network is "monet.'* 
Monet has a list of known ethemet hosts; if it receives mail for any of them, it can 
do direct delivery. If it receives mail for any unknown host, it just passes it directly 
to "ucbvax," the Berkeley master host. Ucbvax may determine that the host name 
is illegal and reject the message, or may be able to do delivery. However, it is 
important to note that when a new ethernet host is added, the only host that must 
have its tables updated is ucbvax; the others may be updated as convenient, but this 
is not critical. 

This picture is slightly muddied due to network connections that are not actu- 
ally located on ucbvax. For example, the Berkeley TCP connection is currently on 
"ucbarpa." However, monet doet not know about this; the information is hidden 
between ucbvax and ucbarpa. Mail going from monet to a TCP host is transferred 
via the ethernet from monet to ucbvax, then via the ethemet from ucbvax to 
ucbarpa, and then is submitted to the Arpanet. Although this involves some extra 
hops, Berkeley feels this is an acceptable tradeoff. 

An interesting point is that it would be possible to update monet to send TCP 
mail directly to ucbarpa if the load got too high: if monet failed to note a host as a 
TCP host, the mail would go via ucbvax as before; and if monet incorrectly sent a 
message to ucbarpa, it would still be sent by ucbarpa to ucbvax as before. The only 
problem that might occur in this scenario is 'looping': if ucbarpa thought that 
ucbvax had the TCP connection and vice versa. For this reason, updates should 
always happen to the master host first. 

This philosophy results as much from the need to have a single source for the 
configuration files (typically built using m4{l) or some similar tool) as any logical 
need. Maintaining more than three separate tables by hand is essential^ an impos- 
sible job. 
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5.5.2.2. Small site - complete Information 

A small site (two or three liMts) may find it more reasonable to have complete 
information at each host. Thb would require that each host know exactly where 
each network connection is, possibly including the names of each host on that net- 
work. As long as the site remains small and the the configuration remains relatively 
static, the update problem will probably not be too great. 

5.3.2.3. Single host 

Thb is in some sense the trivial case. The only major issue is trying to insure 
that you don't have to know too much about your environment. For example, if 
you have a UUCP connection you might find it useful to know about the names of 
hosts connected directly to you, but this is really not necessary since this may be 
determined from the syntax. 

5.3.3. Relevant laauee 

The canonical form you use should almost certainly be as specified in the Arpanet 
protocols RFC819 and RFC822. Copies c^ these RFC's are included on the tendmail 
tape as doc/rfc819.lpr and doe/rfe88S.lpr. 

RFC822 describes the format of the mail message itself. Sendmail follows this 
RFC closely, to the extent that many of the standards described in this document can 
not be changed without changing the code. In particular, the following characters have 
special interpretations: 

<>()'\ 

Any attempt to use these characters tot other than their RFC822 purpose in addresses 
is probably doomed to disaster. 

RFC819 describes the specifics of the domain-based addressing. This is touched 
on in RFC822 as well. Essentially each host is given a name which is a right-to-left dot 
qualified pseudo-path from a distinguished root. The elements of the path need not be 
physical hosts; the domain is logical rather than physical. For example, at Berkeley 
one legal host is "a.cc.berkeley.arpa". Reading from right to left, "arpa" is a top level 
domain (related to, but not limited to, the physical Arpanet), "berkeley" is both an 
Arpanet host and a logical domain which is actually interpreted by a host called ucbvax 
(the "major" host for this domain), "cc" represents the Computer Center, (in this case 
a strictly logical entity), and "a" is a host in the Computer Center; this particular host 
happens to be connected via berknet, the Berkeley network, but other hosts might be 
connected via one of two ethernets or some other network. 

Be aware when reading RFC819 that there are a number of errors in it. 

5.3.4. How to proceed 

Once you have decided on a philosophy, it is worth examining the available 
configuration tables to decide if any of them are close enough to steal major parts of. 
Even under the worst of conditions, there is a fair amount of boiler plate that can be 
collected safely. 

The next step is to build ruleset three. This will be the hardest pvti of the job. 
Beware of doing too much to the address in this ruleset, since anything you do will 
reflect through to the message. In particular, stripping of locaJ domains is best 
deferred, since this can leave you with addresses with no domain spec at all. Since 
sendmail likes to append the sending domain to addresses with no domain, this can 
change the semantics of addresses. Also try to avoid fully qualifying domains in this 
ruleset. Although technically legal, this can lead to unpleasantly and unnecessarify long 
addresses reflected into messages. The Berkeley configuration files define ruleset nine to 
qualify domain names and strip loc^ domains. This is called from ruleset zero to get 

Version 4.2 Last Mod 8/20/83 



Sendmall InitaUatlon and Operation Guide SO 



all addresses into a cleaner form. 

Once yon have ruleset three flnbhed, the other mlesets shoald be relatively 
trivial. If yon need hints, examine the supplied c(»ifigarati(n tables. 

5.3.5. Testing tlie rewriting rules - tlie -bt flag 

When yon build a configuration table, you can do a certain amount <tf testing 
using the "test mode" of eendmail. For example, you could invoke «en(fmai/ as: 

sendmail -bt -Ctest.cf 

which would read the configuration file le«f.c/and enter test mode. In this mode, you 
enter lines of the form: 

rwset address 

where rwset is the rewriting set you want to use and addregf is an address to appfy the 
set to. Test mode shows you the steps it takes as it proceeds, finally showing you the 
address it ends up with. You may use a comma separated list of rwsets for sequential 
application of rules to an input; ruleset three is always applied first. For example: 

1,21,4 monet:bollard 

first applies ruleset three to the input "monet:bollard." Ruleset one is then applied to 
the output of ruleset three, followed similariy by rulesets twenty-one and four. 

If you need more detail, you can also use the -dSl flag to turn on more debug- 
ging. For example, 

sendmail -bt -d21.99 

turns on an incredible amount of informati(Hi; a single word address is probably going 
to print out several pages worth of information. 

5^.6. Building mailer deseriptions 

To add an outgoing mailer to your mail qrstem, you will have to define the 

characteristics of the mailer. 

Each mailer must have an internal name. This can be arbitrary, except that the 
names "local" and "prog" must be defined. 

The pathname of the mailer must be given in the P field. If this mailer should be 
accessed via an IPC connection, use the string "[IPC]" instead. 

The F field defines the mailer flags. You should specify an 'T' or "r" flag to pass 
the name of the sender as a -f or -r flag respectively. These flags are only passed if 
they were passed to sendmaU, so that mailers that give errors under some circumstances 
can be placated. If the mailer is not picky you can just specify "-f $g" in the argv 
template. If the mailer must be called as root the "S" flag should be given; this will 
not reset the userid before calling the mailer'. If this mailer is local (i.e., will perform 
final delivery rather than another network hop) the "1" flag should be given. Quote 
characters (backslashes and " marks) can be stripped from addresses if the "s" flag is 
specified; if this is not given they are passed through. If the mailer is capable of send- 
ing to more than one user on the same host in a single transaction the "m" flag should 
be stated. If this flag is on, then the argv template containing $u will be repeated for 
each unique user on a given host. The "e" flag will mark the mailer as l)eing "expen- 
sive," which will cause sendmail to defer connection until a queue run^ 

An unusual case is the "C" flag. This flag applies to the mailer that the message 
is received from, rather than the mailer being sent to; if set, the domain spec of the 



*Stndmait must be nmning setaid to root for thia to work. 

*r)kt "c" confignntioB optioi must be sivea for this to be effecthre. 
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sender (i.e., the "Qhost.d<Mnaiii" part) is saved and is appended to any addresses in the 
message that do not already contain a domain spec. For example, a message of the 
form: 

From: ericQucbarpa 

To: wDJ®monet, mckusick 

will be modified to: 

From: eric®ucbarpa 

To: wnj®monet, mckusickQucbarpa 

if and only t/the "C" flag is defined in the mailer corresponding to "ericQucbarpa." 

Other flags are described in Appendix C. 

The S and R fields in the mailer description are per-mailer rewriting sets to be 
applied to sender and recipient addresses respectively. These are applied after the 
sending domain is appended and the general rewriting sets (numbers one and two) are 
applied, but before the output rewrite (ruleset four) is applied. A typical use is to 
append the current domain to addresses that do not already have a domain. For exam- 
ple, a header of the form: 

From: eric 
might be changed to be: 

From: eric®ucbarpa 
or 

From: ucbvax!eric 

depending on the domain it is being shipped into. These sets can also be used to do 
special purpose output rewriting in cooperation with ruleset four. 

The E field defines the string to use as an end-of-line indication. A string contain- 
ing only newline is the default. The usual backslash escapes (\r, \n, \f, \b) may be 
used. 

Finally, an argv template is given as the E field. It may have embedded spaces. 
If there is no argv with a $u macro in it, sendmail will speak SMTP to the mailer. If 
the pathname for this mailer b "|IPC|," the argv should be 

IPC $h I port ) 

where port is the optional port number to connect to. 

For example, the specifications: 

Mlocal, P=/bin/mail, F=rlsm S=10, R=20, A=mail -<1 $u 
Mether,P=|IPCl, F=meC, S=ll, R=21, A=IPC $h, M= 100000 

specifies a mailer to do local delivery and a mailer for ethernet delivery. The first is 
called "local," is located in the file '7^*"/™^^»" *akes a picky -r flag, does local 
delivery, quotes should be stripped from addresses, and multiple users can be delivered 
at once; ruleset ten should be applied to sender addresses in the message and ruleset 
twenty should be applied to recipient addresses; the argv to send to a message will be 
the word "mail," the word "-d," and words containing the name of the receiving user. 
If a -r flag is inserted it will be between the words "mail" and "-d." The second mailer 
is called "ether," it should be connected to via an IPC connection, it can handle multi- 
ple users at once, connections should be deferred, and any domain from the sender 
address should be appended to any receiver name without a domain; sender addresses 
should be processed by ruleset eleven and recipient addresses by ruleset twenty-one. 
There is a 100,(M)0 byte limit on messages passed through this mailer. 
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COMMAND LINE FLAGS 



Arguments must be presented with flags before addresses. The flags are: 

-f addr The sender's machine address is addr. This flag is ignored unless the real user is 

listed as a "trusted user" or if addr contains an exclamation point (because oi 
certain restrictions in UUCP). 

-r addr An obsolete form of -f. 

-h cnt Sets the "hop count" to ent. This represents the number of times this message 

has been processed by sendmail (to the extent that it is supported by the underly- 
ing networks). Cnt is incremented during processing, and if it reaches MAXHOP 
(currently 30) sendmaii throws away the message with an error. 

-Fname Sets the full name of this user to name. 

-n Don't do aliasing or forwarding. 

-t Read the header for "To:", "Cc:", and "Bcc:" lines, and send to everycme listed 

in those lists. The "Bcc:" line will be deleted before sending. Any addresses in 
the argument vector will be deleted from the send list. 

-hx Set operation mode to x. Operation modes are: 

m Deliver mail (default) 

a Run in arpanet mode (see below) 

8 Speak SMTF on input side 

d Run as a daemon 

t Run in test mode 

V Just verify addresses, don't collect or deliver 

i Initialize the alias database 

p Print the mail queue 

z Freeze the configuration file 

The special processing for the ARPANET includes reading the "From:" line from 
the header to find the sender, printing ARPANETT style messages (preceded by 
three digit reply codes for compatibility with the FTP protocol |Neigus73, Pos- 
tel74, Po6tel77]), and ending lines of error messages with <CRLF>. 

-q<tme Try to process the queued up mail. If the time is given, a iendmail will run 

through the queue at the specified interval to deliver queued mail; otherwise, it 
only runs once. 

-CJUe Use a different configuration file. 

-dlevei Set debugging level. 

-ox value Set option x to the specified va/ue. These options are described in Appendix B. 

There are a number of options that may be q>ecified as primitive flags (provided for compa- 
tibility with delivermail). These are the e, i, m, and v options. Also, the f option may be 
specified as the -■ flag. 
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APPENDIX B 
CONFIGURATION OPTIONS 



The following options may be set using the -o flag on the command line or the O line in 
the configuration file: 

Kfile Use the named file as the alias file. If no file is specified, use aliaats in the 

current directory. 

a If set, wait for an "Q:0" entry to exbt in the alias database before starting up. 

If it does not appear in five minutes, rebuild the database. 

c If an outgoing mailer is marked as being expensive, don't connect immediately. 

This requires that queueing be compiled in, since it will depend on a queue run 
process to actually send the mail. 

dz Deliver in mode x. Legal modes are: 

i Deliver interactively (qrnchronously) 

b Deliver in background (asynchronously) 

q Just queue the message (deliver during queue run) 

D If set, rebuild the alias database if necessary and possible. If this option is not 

set, sendmail will never rebuild the alias database unless explicitly requested 
using -bl. 

ex Dispose of errors using mode x. The values for x are: 

p Print error messages (default) 

q No messages, just give exit status 

m Mail back errors 

w Write back errors (mail if user not logged in) 

e Mail back errors and give zero exit stat always 

Fn The temporaiy file mode, in octal. 644 and 600 are good choices. 

f Save Unix-style "From" lines at the front of headers. Normally they are 

assumed redundant and discarded. 

gn Set the default group id for mailers to run in to n. 

Hfile Specify the help file for SMTP. 

i Ignore dots in incoming messages. 

L n Set the default log level to n. 

Mx value Set the macro x to vaiue. This is intended only for use from the command line. 

m Send to me too, even if I am in an alias expansion. 

o Assume that the headers may be in old format, i.e., spaces delimit names. This 

actually turns on an adaq^tive algorithm: if any recipient address contains a 
comma, parenthesis, or angle bracket, it will be assumed that commas already 
exist. If this fiag is not on, only commas delimit names. Headers are always out- 
put with commas between the names. 

Qdir Use the named dir as the queue directory. 

Ttime Timeout reads after time interval. 
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S^e Log statistics in the named JUt, 

8 Be super-safe when running things, i.e., always instantiate the queue file, even if 

you are going to attempt immediate delivery. Sendmail always instantiates the 
queue file before returning contrcJ the the client under any circumstances. 

Ttime Set the queue timeout to time. After this interval, messages that have not been 

successfully sent will be returned to the sender. 

tS,D Set the local timezone name to S for standard time and D for daylight time; this 

is only used under version six. 

un Set the default userid tcf mailers to n. Mailers without the S flag in the mailer 

definition will run as this user. 

V Run in verbose mode. 
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MAILER FLAGS 



The following flags may be set in the mailer description. 

f The mailer wants a -f from flag, but onty if this b a network fwward operation (i.e., the 
mailer will give an error if the executing user does not have special permissions). 

r Same as f, but sends a -r flag. 

S Don't reset the userid before calling the maUer. This would be used in a secure environment 
where sendmail ran as root. This could be used to avoid forged addresses. This flag is 
suppressed if given from an "unsafe" environment (e.g, a user's mail.cf file). 

n Do not insert a UNIX-style "From" line on the front of the message. 

1 This mailer is local (i.e., final delivery will be performed). 

s Strip quote characters off of the address before calling the mailer. 

m This mailer can send to multiple users on the same host in one transaction. When a lu 
macro occurs in the argv part of the mailer definition, that field will be repeated as necessary 
for all qualifying users. 

F This mailer wants a "From:" header line. 

D This mailer wants a "Date:" header line. 

M This mailer wants a "Message-Id:" header line. 

X This mailer wants a "Full-Name:" header line. 

P This mailer wants a "Return-Path:" line. 

u Upper case should be preserved in user names for this mailer. 

h Upper case should be preserved in host names for this mailer. 

A This is an Arpanet-compatible mailer, and all appropriate modes should be set. 

U This mailer wants Unix-style "From" lines with the ugly UUCP-style "remote from 
<host>" on the end. 

e This mailer is expensive to connect to, so tiy to avoid connecting normalliy; any necessary 
connection will occur during a queue run. 

X This mailer want to use the hidden dot algorithm as specified in RFC821; basically, any line 
beginning with a dot will have an extra dot prepended (to be stripped at the other end). 
This insures that lines in the message containing a dot will not terminate the message prem»> 
turely. 

L Limit the line lengths as specified in RFC821. 

P Use the return-path in the SMTP "MAIL FROM:" conunand rather than just the return 
address; although thu is required in RFC821, many hosts do not process return paths prop* 
erly. 

I This mailer will be speaking SMTP to another tendmail - as such it can use special protocol 
features. This option is not required (i.e., if this option is omitted the transmission will still 
operate successfully, although perhaps not as efficiently as possible). 

C If mail is received from a mailer with this flag set, any addresses in the header that do not 
have an at sign ("3") after being rewritten by ruleset three will have the "Qdomain" clause 
from the sender tacked on. This allows mail with headers of the term: 
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From: aseraQhoeta 
To: userbQhostb, userc 

to be rewritten as: 

From: useraQhosta 

To: userbQhostb, osercOhoeta 

automatically. 



Version 4.2 Last Mod 8/S0/8S 



APPENDIX D 
SUMMARY OP SUPPORT FILES 



This is a summary of the support files that tendmail creates ot generates. 

usr/lib/sendmail 

The binary of gendmail. 

usr/bin/newaliases 

A link to /usr/lib/sendmail; causes the alias database to be rebuilt. Running this 
program is completely equivalent to giving tendmail the -bi flag. 

usr/lib/sendmail.cf 

The configuration file, in textual tona. 

usr/lib/sendmail. fc 

The configuration file represented as a mem<^ image. 

usr/lib/sendmaii.hf 

The SMTP help file. 

usr/lib/sendmail.st 

A statistics file; need not be present. 

usr/Iib/aliases The textual version of the alias file. 

usr/lib/aliases. {pag.dir } 

The alias file in dbm{3) format. 

usr/etc/in .sy slog 

The program to do logging. 

etc/syslog.conf The configuration file for syslog. 

etc/syslog.pid Contains the process id of the currently running syslog. 

usr/spool/mqueue 

The directory in which the mail queue and temporary files reside. 

usr/spool/mqueue/qf* 

Control (queue) files for messages. 

usr/spool/mqueue/df* 

Data files. 

usr/spool/mqueue/lf* 

Lock files 

usr/spool/mqueue/tf* 

Temporary versions of the qf files, used during queue file rebuild. 

usr/spool/mqueue/nf* 

A file used when creating a unique id. 

usr/spool/mqueue/xf* 

A transcript of the current session. 
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1. Introduction 

Uucp is a series of programs designed such that UNDCf systems can communicate with each 
other using either dial-up or hardwired communication lines. Uucp transfers files between UNIX 
systems, and can also run commands on remote machines. The first version of the system was 
designed and implemented by M. E. Lesk. This paper describes the current (second) implemen- 
tation of the system. This document ^ves a detailed description of the current implementation 
of uucp. It is designed for use by an administrator or installer of the system. It is not meant as 
a user's guide. 

Uucp is a batch operation. Files are created in a spool directory for processing by the uucp dae- 
mons. There are three types of files used for the execution of work: Data files contain data for 
transfer to remote systems; Work files contain directions for file transfers between systems; 
Execute files are scripts for UNIX commands that involve the resources of one or more systems. 

There are four primary programs involved in ««cp's operation: 

uucp builds work files and gathers data files in the spool directory for data transmis- 

sion. 

uux creates work files and execute files, and gathers data files for the remote execu- 

tion of UNIX commands. 

uucico executes the work files for data transmission. 

uux(fi executes the scripts for UNIX command execution. 

There are two administrative programs: 

uulog gathers temporary log files that may occur due to lockout of the uucp log file 

and reports some information such as copy requests and completion status. 

unclean removes old files from the spool directory. 

The remaining sections of this manual describes the operation of each program, security, instal- 
lation details, files required for execution, and administration of the uucp system. 

2. UUCP - UNIX to UNIX File Copy 

The uucp command was is designed to look like cp(\) to the user. The syntax is: 

uucp [ option ] ... source . . . destination 

where the source and destination may contain the prefix system-name! , which indicates the sys- 
tem where the file or files reside or where they will be copied. 

Uucp has several options: 

-d Make directories when necessary for copying the file. 

-c Don't copy source files to the spool directory, but use the specified source when 

the actual transfer takes place. Note that the files, and all directories leading to 
them, must be accessible by everybody. 

-esys Send this job to system sys to execute. Note that this only works when the sys- 

tem sys allows uux(fi to execute a uucp command. See the sections entitled 
Uuxqt and Security. 



t UNIX is a trademark of Bell Laboratories. 
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-C Force the source files to be copied to the spool directory. 

-f Do not make directories. 

-gletter Put letter in as the grade in the name of the work file. This can be used to 
change the order of work for a particular machine. 

-m Send mail to the requester on completion of the work. 

-nuser Notify user on the remote machine that a file has been sent. 

Then there are options available for debugging: 

-sdir Use dir as the spool directory. 

-r Queue the job but do not start uucico program. 

-xrium Num is a level number between 1 and 9; higher numbers give more debugging 
output. 

The destination may be a directory name, in which case the file name is taken from the last 
part of the source's name. If the directory exists, it must be writable by everybody. Note that 
if the destination is a directory name and the -d option is specified to create the directory, the 
directory name must be followed by "/ "• The source name can contain special shell characters 
such as ?, ♦, and [ and ]. These are expanded on the appropriate system. 

The command 

uucp *.c usg!/usr/dan 

sets up the transfer of all files whose names end with .c to the /usr/dari directory on the usg 
machine. 

The source and/or destination names may also contain a "user prefix. This translates to the 
login directory of user on the specified system. File names beginning with "~/" translate into 
the public directory (usually / usr/ spool/ uucppublic) on the remote system. For names with par^ 
tial path-names, the current directory is prepended to the file name. File names beginning with 
../ are not permitted for security reasons. 

The command 

uucp usg!~dan/*.h ~dan 

sets up the transfer of files whose names end with ,h in dan's login directory on system usg to 
dan's local login directory. 

For each source file, uucp checks the source and destination file-names, the system-part of each 
argument, and the options to classify the work into several types: 

[1] Copy source to destination on local system. 

[2] Receive files from other systems. 

[3] Send files to a remote system. 

[4] Send files from remote systems to another remote system. 

[5] Receive files from remote systems when the source contains special shell characters as 
mentioned above. 

[6] Request that the uucp command be executed by a remote system. 

After the work has been set up in the spool directory, the uucico program is started to try to 
contact the other machine and execute the work (unless the — r option was specified). 
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2.1. Type 1 ~ Local Copy 

The copy is done locally. The -m and -n options are not honored in this case. 

2.2. Type 2 - Receive Files 

A work file is created or appended with a one line entry for each request. The upper limit to the 
number of files per work file is set in uucp.h The default setting is 20. After the limit has been 
reached, a new work file is created. 

All work files and execute files use a blank as the field separator. The fields for these entries are 
given below. 

[1] R 

[2] The full path-name of the source or a ~something/path-name. The "something part is 
expanded on the remote system. 

[3] The full path-name of the destination file. If the 'something notation is used, it is 
immediately expanded. 

[4] The user's login name. 

[5] A "-'' followed by an option list. The options -m and -d may appear. 

2.3. Type 3 - Send Files 

Each source file is copied into a data file in the spool directory. (A -c option on the titicp com- 
mand prevents the data file from being made. In this case, the file is transmitted from the indi- 
cated source.) The fields for these entries are given below. 

[1] s 

[2] The full-path name of the source file. 

[3] The full-path name of the destination or " something/file-name. 

[4] The user's login name. 

[5] A "-" followed by an option list. The options -d, -m, and -n may appear. 

[6] The name of the data file in the spool directory. A dummy name, "D.O" is used when 
the -c option is specified. 

[7] The file mode bits of the source file in octal print format (666 for instance). 

[8] The user on the remote system who should be notified upon completion of the file copy 
when the -n option is specified. 

2.4. Type 4 and Type 5 - Remote UUCP Required 

Uucp generates a uucp command and sends it to the remote machine; the remote uucico exe- 
cutes the uucp command. 
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2.5. Type 6 - Remote Execution 

Remote execution occurs when the -e option is used. In this case, the uux facility is used to 
create and send the request. This requires that the remote uuzqi program allows the uuep com- 
mand to be executed. 

3. UUX - UNIX to UNIX Execution 

The uux command sets up the execution of a UNIX command where the execution machine 
and/or some of the files are remote. The syntax of the uuz command is 

uux [ - ] [ option ] ... command-string 

where the command-string is made up of one or more arguments. All special shell characters 
such as <, >, I, and ^ , must be quoted either by quoting the entire command-string or quoting 
the special character as a separate argument. 

Within the command-string, the command and file names may contain a ty»tcm-name! prefix. 
Arguments which do not contain a ! character are assumed to be part of the command string 
and are not treated as files (that is, uux does not copy them to the execution machine). 

An argument containing a ! but should not be treated as a file at the present time, can be 
escaped by surrounding the argument in parentheses ( and ). Note that the ( and ) characters 
themselves must usually be escaped with a \ character. 

The "-" indicates that the standard input for command-string should be inherited from the 
standard input of the uux command. 

The following options are available for uux: 

Read from the standard input. 

-x Read from the standard input. 

-n Do not notify the requestor (by mail) of completion status. 

-z Only notify the requestor (by mail) of non-zero completion status. 

The following options are available for debugging: 

-r Don't start uucico or uuxqt after queuing the job. 

-xnum Num is a level number between 1 and 9; higher numbers give more debugging 

output. 

The command: 

pr abc I uux - usgflpr 
sets up the output of the 

pr abc 

command as standard input to an Ipr command to be executed on system usg. 

Uux generates an execute file containing the names of the files required for execution (including 
standard input), the user's login name, the destination of the standard output, and the com- 
mand to be executed. This execute file file is either put in the spool directory for local execution 
or sent to the remote system using a send command (uuep type 3 command, described previ- 
ously). 

For required files that are not on the execution machine, uux generates receive command files 
{uucp type 2 command, described previously). The uucico program puts these command- files on 
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the execution machine for execution. 

The execute file contains a script that is processed by the uux^ program. It is made up of 
several lines, each of which contains an identification character and one or more arguments. 
The lines are described in the subsections below. Here is a summary of the types of lines that 
appear in the file. They are described in detail in the sections following. 

User Line Identifies the requestor's login name and system. 

File Line Identifies a filename for transmission. 

Standard Input Line 

Specifies a standard input file. 

Standard Output Line 

Specifies a standard output file. 

Command Line 

Identifies a UNIX system command for uuxqt to execute. 

3.1. User Line 

U user system 
where the user and system are the requester's login name and system. 

3.2. Required File Line 

F file-name real-name 

where file-name is a unique name used for file transmission and real-name is the last part of the 
actual file name (contains no path information). 

Zero or more of these lines may be present. The uuxqt program checks for the existence of all 
these files before the command is executed. 

3.3. Standard Input Line 

I file- name 

The standard input is either specified by a < in the command-string or inherited from the stan- 
dard input of the uux command if the "-'' option is used. If a standard input is not specified, 
I devjnuU is used. Note that if there is a standard input specified, it will also appear in an 'T'' 
line. 

3.4. Standard Output Line 

O file-name system-name 

The standard output is specified by a > within the command-string. If a standard output is 
not specified, / dev/nuU is used. Note that the appending to a file by using >> is not imple- 
mented. 
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3.5. Command Line 

C command [ arguments ] ... 

The arguments are those specified in the command-string. The standard input and standard 
output will not appear on this line. All required fiiet are moved to the execution directory (usu- 
ally I usr I libf uucpj .XQTDIR) and the UNIX command is executed using the shell specified in the 
uuep.h header file. In addition, a shell 'TATH'^ statement is prepended to the command line as 
specified in the uuxqt program. 

Note that a check is made to see that the command is allowed as specified in the uttzqt program. 
After execution, the standard output is copied or sent to the proper place. 

4. UUXQT - UUCP Command Execution 

The uuzqt program executes scripts generated by uui. 

The uuxqt program may be started by either the uueico or uuz programs or a daemon specified 
by a crontab entry. Uuxqt scans the spool directory for execute files (prefix "X."). Each execute 
file is checked to see if all the required files are available and if so, the command line is verified 
and executed. 

The execute file is described in the section entitled ««2, above. 

The execution is accomplished by executing a 

sh -c 

of the command line after appropriate standard input and standard output have been opened. 
If a standard output is specified, the program creates a send command, or copies the output file 
as appropriate. 

Uuxqt accepts the standard debugging option: 

-xnum Num is a level number between 1 and 9; higher numbers give more debug out- 
put. 

5. UUCICO - Copy In, Copy Out 

The uueico program performs several major functions: 

• Scan the spool directory for work. 

• Place a call to a remote system. 

• Negotiate a line protocol to be used. 

• Execute all requests from both systems. 

• Log work requests and work completions. 

Uueico may be started in several ways: 

a. by a system daemon specified in a crontab entry, 

b. by one of the uucp, uux, uuxqt or uueico programs, 

c. directly by the user (this is usually for testing), 

d. by a remote system. The uueico program should be specified as the "shell" field in 
the /etc/pasawd file for the logins used by remote systems to access uucp. 



7 January 1984 



UUCP Implementation Description UUCICO - Copy In, Copy Out 

When started by method a, b or c, uueieo is considered to be in MASTER mode. In this mode, 
a connection is made to a remote system. If started by a remote system (method d), uucico is 
considered to be in SLA VE mode. 

The MASTER mode operates in one of two ways. If no system name is specified (-s option not 
specified) uucico scans the spool directory for systems to call. If a system name is specified, that 
system is called, and work is only done for that system. 

Uucico is generally started by another program. There are several options used for execution: 

-rl Start uucico in MASTER mode. This is used when uucico is started by a pro- 

gram or "cron" shell. 

-ssyB Do work only for system sy$. If -s is specified, a call to the specified system is 

made even if there is no work for system syt in the spool directory. This is use- 
ful for polling systems that do not have the hardware to initiate a connection. 

The following options are used primarily for debugging: 

-ddir Use directory dir for the spool directory. 

-xnum Num is a level number between 1 and 0; higher numbers give more debugging 
output. 

The next part of this section describes the major steps within the uucico program. 

5.1. Scan For Work 

The names of the work related files in the spool directory have format 
type . system-name grade number 

type is an upper case letter { C - copy command file, D - data file, X- execute file), 

system- name 

is the remote system, truncated to seven characters. 

grade is a character, 

number is a four digit, hexadecimal, zero padded sequence number. 

The file 

C.res45n0031 

would be a work file for a file transfer between the local machine and the '*res45'* machine. 

The scan for work is done by looking through the spool directory for work files (files with prefix 
"C"). A list is made of all systems to be called. Uucico then calls each system and processes 
all work files. 

5.2. Call Remote System 

The call^ is made using information from several files that reside in the uucp program directory 
(usually /usr/ lib/ uucp). At the start of the call process, a lock is set to prevent multiple conver- 
sations between the same two systems. 

The L .sys file contains information required to make the remote connection: 

[1] system name, 
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[2] times to call the system (days-of-week and timeshof-day) and the minimum time delay 
before retry, 

[3] device or device type to be used for call, 

[4] line class (this is the line speed on almost all systems), 

[5] phone number if field [3] is A CU or the device if not ACU, 

[6] login information (zero or more fields), 

The time field is checked against the present time to see if the call should be made. The phone 
number may contain abbreviations (for example, mh, py, boston) that get translated into dial 
sequences using the L-dialcode» file. 

The L- devices file is scanned using fields [3] and [4] from the L.sys file to find an available dev- 
ice for the call. The program tries each devices that satisfy [3] and [4] until a call is made, or no 
more devices can be tried. If a device is successfully opened, a lock file is created. If the call is 
completed, the login information (field [6] of L ,*ys ) is used to login. 

The conversation between the two uucico programs begins with a handshake started by the 
called (SLAVE) system. The SLAVE sends a message to let the MASTER know it is ready to 
receive the system identification and conversation sequence number. The SLAVE verifies the 
response from the MASTER and if acceptable, protocol selection be^ns. The SLA VE can also 
reply with a "call-back required'' message, in which case the current conversation is terminated. 

5.3. Line Protocol Selection 

The remote system sends a message: 

Pproto-list 
where proto-list is a string of characters, each representing a line protocol. 

The calling program checks protO'liat for a letter corresponding to an available line protocol and 
returns a use-protocol message. The use-protocol message is 

Vcode 

where code is either a one character protocol letter or "N", which means there is no common 
protocol. The only protocol which is currently implemented is "g", which uses the packet 
driver. 

5.4. Work Processing 

The MASTER program does a work search similar to the one used in the Scan For Work sec- 
tion described above (the MASTER has been specified by the "-rl" uucico option). Each mes- 
sage used during the work processing is specified by the first character of the message: 

S send a file, 

R receive a file, 

C copy complete, 

X execute a uucp command, 

H hangup. 

The MASTER sends R, S or X messages until all work for the remote system is complete, at 
which point an //message is sent. The SLAVE replies with SY, SNy RY, RN, HY, HN, XYy or 
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XN, corresponding to yes or no for each request. 

An N response can be followed by a number giving the reson for the failure: 

NO 

Copy failed (reason not given by remote system). 

Nl 

Local access to file denied. 

N2 

Remote access to path or file denied. 

N3 

System error - bad uttcp command generated. 

N4 

Remote system cannot create temporary file. 

N5 

Cannot copy to file or directory - file left in pubdir/user/fUe. 

m 

Cannot copy to file or directory - file left in pubdir/user/fUe. 

The send and receive replies are based on permission to access the requested file or directory 
using the USERFILE and read/ write permissions of the file or directory. 

After each file is copied into the spool directory of the receiving system, a copy-complete mes- 
sage is sent by the receiver of the file. The message CY is sent if the file has successfully been 
moved from the spool directory to the destination. If the file was not successfully moved from 
the spool directory to the destination, a CN message is sent, the file is put in the public direc- 
tory (usually / u»r/ spool/ uucppublic), and the requester is notified by mail. 

The requests and results are logged on both systems. 

The hangup response is determined by a work scan of the SLA VETs spool directory. If work for 
the remote system exists an HN message is sent and the programs switch roles. If no work 
exists, an HY response is sent. 

5.5. Conversation Termination 

When the MASTER receives a HY message, the MASTER echoes the message back to the 
SLA VE and the protocols are turned ofif. Each program sends a final "OO" (Over and Out) 
message to the other. The original SLAVE program cleans up and terminate. The MASTER 
then proceeds to call other systems unless a "-s" option was specified. 

6. UULOG - UUCP Log Inquiry 

When a vuep program can not make a log entry directly into the LOGFILE an individual log 
file is created: a file with prefix LOG. This sometimes occurs when more than one uucp process 
is running. Periodically, uulog may be executed to append these files to the LOGFILE. 

The uulog program may also be used to request the output of LOGFILE entries. The request is 
specified by the use of the options: 

-ssys Print entries where sys is the remote system name, 

-u««cr Print entries for user tutr. 
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The intersection of lines satisfying the two options is output. A null sys or user means all sys- 
tem names or users respectively. 

Debugging options available are: 

-xnum Num is a level number between 1 and 0; higher numbers give more debug out- 
put. 

-nsecs Time out lock on log file if older than sect seconds. 

7. UUCLEAN - UUCP Spool Directory Cleanup 

Uuclean is typically started by the uucp daily daemon. Its function is to remove files from the 
spool directory that are more than three days old. These are usually files for work that can not 
be completed. The requester of this work is notified that the files have been deleted. 

There are several options: 

-drfir The directory to be scanned is dir. 

-m Send mail to the owner of each file being removed. Note that most files put into 

the spool directory are owned by the owner of the uucp programs since the 
setuid bit will be set on these programs. This mail is sometimes useful for 
administration. 

-nhoura Change the aging time from 72 hours to hours hours. 

-pprc Examine files with prefix pre for deletion. Up to 10 of these options may be 

specified. 

-X num This is the level of debugging output desired. 

8. Security 



=^ The uucp system, left unrestricted, will let any outside user execute any commands and copy 
out/ in any file that is readable/ writable by a uucp login user. It is up to the individual sites to be 
aware of this and apply the protections that they feel are necessary. 



There are several security features available aside from the normal file mode protections. These 
must be set up by the administrator of the uucp system. 

• The login for uucp does not get a standard shell. Instead, the uucico program is started so 
that ail work is done through uucico. 

• The owner of the uucp programs should be an administrative login. It should not be one of 
the logins used for remote system access to uucp. 

• All uucp logins should have passwords. 

• A path check is done on file names that are to be sent or received. The USERFILE supplies 
the information for these checks. The USERFILE can also be set up to require call-back for 
certain login-ids. See the "Files Required For Execution" section for the file description. 

• A conversation sequence count can be set up so that the called system can be more confident 
of the caller's identity. 

• The uuxqt program reads a file containing a list of commands that it will execute. A 
"PATH" shell statement is prepended to the command line as specified in the uux(fi pro- 
gram. The installer may modify the list or remove the restrictions as desired. 
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• The L,8ys file should be owned by the uucp administrative login and have mode 0400 to 
protect the phone numbers and login information for remote sites. 

• The programs uucp, uucico, uuz, uuxqt, uulog, and uucUan should be owned by the uucp 
administrative login, have the setuid bit set, and have only execute permissions. 

9. UUCP Installation 

It is assumed that the login name used by a remote computer to call into a local computer is not 
the same as the login name of a normal user or the uucp administrative lo^n. However, several 
remote computers may use the same login name. It is suggested that the installer follow the 
convention of using the letter "U" followed by the system name as the login name for each sys- 
tem. For example, use login name Uusgtor the usg system. 

Each computer should be given a unique iystem name that is transmitted at the start of each 
call. This name identifies the calling machine to the called machine. The login/system names 
are used for security as described later in the USERFILE section. 

There are several source modifications that may be required before the system programs are 
compiled. These relate to the directories, local system name, and attributes of the local environ- 
ment. 

The uucp system uses several directories: 

sources (/usr/src/cmd/uucp) - This directory contains the uucp system source files. 

program (/usr/lib/uucp) - This is the directory used for some of the executable system 
programs and the system files. Some of the programs reside in /utr/bin. 

spool (/usr/spool/uucp) - This is the uucp system spool directory. 

xqtdir (/usr/lib/uucp/ .XQTDIR) - This directory is used during execution of the uux 

scripts. 

The names in parentheses above are the default values for the directories. The italicized names 
sources, program, xqtdir, and spool are used in the following text to represent the appropriate 
directory names. 

There are two files that may require modification, namely the Makefile file and the uucp.h file. 
In addition, the uuxqt.c program may be modified as indicated in the section entitled Security, 
above. The following sections describe the modifications. 

9.1. uucp.h Modification 

Several manifests in uucp,h may need modification for the local system environment: 

UNAME should be defined if the '^uname*' function is available. 

ACULAST is the character required by the ACU as the last character. For most systems, 
it is a '*-". This is only relevant if you are using a DNll autodialler. 

DIALOUT should be defined if the C library routine "dialout" is available. 

UUDIR should be defined if the uucp subdirectory tyskludge is being used. 

UUNAME should be defined if the system name should be read from the SYSTEMNAME 
file. 

UUSTAT should be defined if you need the uustat program. 
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UUSUB should be defined if you need the utuub program. 

9.2. Makefile Modification 

There are several make variable definitions that may need modification: 

INSDIR is the program directory (for example, INSDIR=/usr/lib/uucp). This parameter 
is used if "make cp'* or "make install" is used. 

PUBDIR is a public directory for remote access. This is also the login directory for 
remote uucp users. It should be the same as that defined in titicp.A. 

SPOOL is the uucp spool directory. This should be the same as that defined in uuep,h. 

XQTDIR is the directory for uuxqt to use for command execution. It is also defined in 
uucp.h. 

OWNER is the administrative login for uucp. 

LIBS should include tyskludge/syskludge.a if the syakludge library it uted. UUDIR 

should be defined in uucp,h. 

CFLAGS add -DVMUNIX if on a VMUNIX system. 

9.3. Compiling the System 

The command: 

make install 

makes the required directories, compiles all programs, sets the proper file modes, and copies the 
programs to the proper directories. This command should be run as root. The command: 

make 

compiles the entire system. 

The programs uucp, uux, and uulog should be put in /uer/bin. The programs utizgl, uucico, and 
unclean should be put in the program directory. 

9.4. Files Required for Execution 

Six files are required for execution. They should reside in the program directory. The field 
separator for all files is a space. The required files are summarized here, and the following sub- 
sections describe them in detail. 

L' devices Contains call unit information. 

L'dialcodes Contains dialcode abbreviations. 

USERFILE Contains user accessibility and constraint information. 

L.sys Contains information about the systems which local uucp programs can call. 

L.cmds Contains commands which uuxqt is allowed to execute. 

SYSTEMNAME 

Contains the name of the system. 
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9.5. L-devices - Call Unit Information File 

L-devices contains call-unit device and hardwired connection information. The special device 
files are assumed to be in the /dev directory. The format for each entry in the L-device» file is: 

type line call-unit speed 

type is a device type such as ACU or DIR. The currently supported device types are 

described later. The field can also be used to specify particular ACUs for some calls 
by using a suffix on the ACU field (ACUDFOSwats, for instance). This name should 
be used in L .sys. 

line is the device for the line (for example, culO if using a DNll, otherwise it is the same 

as the call-unit field). 

call-unit is the automatic call unit associated with line (for example, cuaO). Hardwired lines 
have a number "0" in this field. 

epeed is the line speed. 

For example, an entry in the L-devices file like this: 

ACU culO cuaO 300 

would be set up for a system that has a DNll device "/*^^^/^^^0" wired to a call-unit 
"/dev/cuaO" for use at 300 baud. An entry like: 

ACUDF03 cuaO cuaO 1200 

would be set up for a system that has a DF03 device "/^^^^/c^^iO" ^^r use at 1200 baud. 

9.6. L-dialcodes - Dial Code Abbreviations File 

L-dialcodea contains the dialcode abbreviations used in the L,iys file (for example, py, mh, bos- 
ton). The entry format is: 

abb dial-seq 

abb is the abbreviation, 

dial-seq is the dial sequence to call that location. 

For example, a line in the L-dialcodes file that looks like: 

py 165- 
would be set up so that entry pyllll would send 165-7777 to the dial-unit. 

9.7. USERFILE 

USERFILE contains user accessibility information. It specifies four types of constraint: 
[l] which files can be accessed by a normal user of the local machine, 
[2] which files can be accessed from a remote computer. 
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[3] which login name is usifd b^ij^'a particular remote computer, 

[4] whether a remote computer^'should be called back in order to confirm its identity. 

Each line in USERFJLE has the forMiat: 

login, sys [ c ] path-na^e [ path-name ] ... 

login is the login name for a user or the remote computer, 

»y$ is the system name for a remote computer, 

c is the optional call-back required flag, 

path-name is a path-name prefix that is acceptable for ty». 

The constraints are implemented as follows. 

[1] When the program is obeying a command stored on the local machine {MASTER mode) 
the path-names allowed are those given on the first line in the USERFILE that has the 
login name of the user who entered the command. If no such line is found, the first line 
with a null login name is used. 

[2] When the program is responding to a command from a remote machine {SLAVE mode) 
the path-names allowed are those given on the first line in the file that has the system 
name that matches the remote machine. If no such line is found, the first one with a 
null system name is used. 

[3] When a remote computer logs in, the login name that it uses must appear in the USER- 
FILE. There may be several lines with the same login name but one of them must 
either have the name of the remote system or must contain a null system name. 

[4] If the line matched in ([3]) contains a "c**, the remote machine is called back before any 
transactions take place. 

Examples 

The line: 

u,m /usr/xyz 

allows machine m to login with name u and request the transfer of files whose names start with 
/usr/zyz. 

The line: 

dan, /usr/dan 

allows the ordinary user dan to issue commands for files whose name starts with /usr/dan. 
(Note that this type of restriction is seldom used.) 

The lines: 

u,m /usr/xyz /usr/spool 
u, /usr/spool 

allows any remote machine to login with name u. If its system name is not m, it can only ask 
to transfer files whose names start with /usr/spool. If it is system m, it can send files from path 
/usr/zyz as well as /usr/spool. 

The lines: 
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root, / 
, /usr 

allow any user to transfer files beginning with juar, but the user with login root can transfer 
any file. Note that any file that is to be transferred must be readable by anybody. The USER- 
FILE is normally set up as follows: 

,myname / 

, /usr/spool/uucppublic 

where myname is the name of the current system. These lines allow any user on the current 
machine to access any file (subject to the normal permissions on the file) for uvcp transfer, 
whereas users on other machines can only access files in /utr/ spool/ uucppublic. 

9.8. L.sys 

Each entry in L.sys represents one system that can be called by the local uucp programs. More 
than one line may be present for a particular system. In this case, the additional lines represent 
alternative communication paths that are tried in sequential order. The fields are described 
below. 

system name 

The name of the remote system. 

time This is a string that indicates the days-of-week and times-of-day when the system 

should be called (for example, MoTuTh0800-1730). 

The day portion may be a list containing some of 
Su Mo Tu We Th Fr Sa 

or it may be Wk for any week-day or Any for any day. 

The time should be a range of times (for example, 080Q-1230). If no time portion is 
specified, any time of day is assumed to be okay for the call. Note that a time r^nge 
that spans 0000 is permitted, for example, 0800-0600 means all times are ok other 
than times between 6 and 8 am. 

A time specification of "None'' is often used for a passive system, that is, one which 
cannot call the specified system. In this case the following fields may be omitted. 
Note that the string "None'' has no special significance, but is merely a string that is 
not a correct time specification. 

Several day-time specifications may be present, separated by a j character. 

An optional subfield is available to indicate the minimum time (minutes) before a 
retry following a failed attempt. The subfield separator is a ",". For example. 
Any ,9 means call any time but don't allow another call until at least 9 minutes after 
* a failure has occurred. 

device This fields either starts with ACU, or is the hardwired device to be used for the call. 
For the hardwired case, the last part of the special file name is used (ttyO, for 
instance). 



7 January 1984 15 



UUCP Installation UUCP Implementation Description 

class This is usually the lin| spied for the call (for example, 300). The exception is when 

the C library routine fdialout" is available in which case this is the dialout class. 

phone The phone number is made up of an optional alphabetic abbreviation and a numeric 
part. The abbreviation should be one that appears in the L-dideode$ file (for exam- 
ple, mh5900, boston995-9980). For the hardwired devices, this field contains the 
same string as used for the device field. 

login The login information is given as a series of fields and subfields in the format 

[ expect send ] . . . 

where expect is the string expected to be read and tend is the string to be sent when 
the expect string is received. 

The expect field may be made up of subfields of the form 

expect [-send-expcct] . . . 

where the »end\s sent if the prior expect is not successfully read and the expect fol- 
lowing the Bend is the next expected string. For example: 

login— login 

expects to see the word login\ if it gets it, the program proceeds to the next field; if 
it does not get login, it sends nuU followed by a new line, then expects login again. 

There are two special names available to be sent during the login sequence. The 
string EOT sends an EOT character and the string BREAK tries to send a BREAK 
character. The BREAK character is simulated using line speed changes and null 
characters and may not work on all devices and/or systems. A number from 1 to 9 
may follow the BREAK. For example, BREAKl sends 1 null character instead of 
the default of 3. Note that BREAKl usually works best for 300/1200 baud lines. 

The following escape sequences are also recognized: 

\r send a carriage-return. 

\n send a newline (linefeed) character. 

\d delay for 1 second. 

\c suppress newline at end of tend string. 

\s send a space. 

A typical entry in the L.sys file would be: 

sys Any ACU 300 mh7654 login:-EOT-login:-BREAK-Iogin: uucp ssword: word 

The expect algorithm matches all or part of the input string as illustrated in the password field 
above. Very complex expect-send sequences are often required if the called system is connected 
to a terminal concentrator or a front end. 

9.9. L.cmds 

L.cmds contains a list of commands which uttxqt is allowed to execute. The commands should 
be one per line. At a minimum, L.cmds should contain the command "rmaiF'. Other com- 
mands often allowed are "rnews", "uusend", and "Ipr". 
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9.10. Device Types 

The currently supported device types are: 



Type Code 


Device 


ACU 


DEC DNll 


ACUDNll 


DEC DNll 


ACUDF02 


DEC DF02 (300 baud only) 


ACUDF03 


DEC DF03 (1200 baud only) 


ACUVENTEL 


Ventel MD212 Plus 


DIR 


Hardwired Line. 



The DNll is only available on DEC PDP-11 and VAX systems. The DEC DF02, DF03, and 
Ventel MD212 Plus can be connected to any system using a standard RS232 terminal interface. 
When connecting one of these devices to a terminal line, the device node (/dev/ttyj) should be 
renamed (to /dev/cuaO for instance) to emphasize that the line is for dialout only and to 
prevent accidentally starting a login process for that line. 

The device type specified in the L- devices file should be one of those listed above, optionally 
qualified further by additional characters after the device type. The device type specified in the 
L,sys file should be a prefix of one of the devices specified in the L- devices file. For example, 
assume you have two DFOS's, one connected to a local telephone line and the other connected to 
a WATS line. The L- devices file could be set up as follows: 

ACUDFGSlocal cuaO cuaO 1200 
ACUDFOSwats cuaO cuaO 1200 

To call a system using only the WATS line, specify ACUDFOSwats in the device type field. 
Similarly, to call a system using the local telephone line, specify ACUDFOSlocal. To call a sys- 
tem using either DF03, specify ACUDF03 in the L,sys file. 

Note that the telephone numbers specified in the L.sys file will have a format dependent on the 
ACU device type. This is a deficiency which may be corrected in the future. 

10. Administration 

This section indicates some events and files that must be administered for the uucp system. 
Some administration can be accomplished by shell files initiated by crontab entries. Others may 
require manual intervention. Some sample shell files are given toward the end of this section. 

10.1. SQFILE - Sequence Check File 

SQFILE is set up in the program directory and contains an entry for each remote system with 
which you agree to perform conversation sequence checks. The initial entry is just the system 
name of the remote system. The first conversation adds the conversation count and the 
date/time of the most resent conversation. These items are updated with each conversation. If 
a sequence check fails, the entry will have to be adjusted manually. Note that this feature is 
rarely used. 
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10.2. TM - Temporary Data FUes 

These files are created in the spool directory while a file is being copied from a remote machine. 
Their names have the form 

TM.pid.ddd 

where pid is a process-id and ddd is a sequential three digit number starting at zero. After the 
entire file is received, the TM file is moved/copied to the requested destination. If processing is 
abnormally terminated the file remains in the spool directory. The leftover files should be 
periodically removed; the unclean program is useful in this regard. The command 

program/ uuclean -pTM 

removes all TM files older than three days. 

10.3. LOG - Log Entry Files 

During execution, log information is appended to the LOGFILE. If the LOGFILE is locked by 
another process, the log information is placed in individual log files with a with a LOG prefix. 
These individual files should be combined into the LOGFILE by using the uulog program. 
Uulog appends the contents of the individual log files onto the end of the LOGFILE. The com- 
mand: 

uulog 

accomplishes the merge. Options are available to print some or all the log entries after the files 
are merged. The LOGF/L^" should be removed periodically. 

The LOG files are created initially with mode 0222. If the program that creates the file ter- 
minates normally, it changes the mode to 0666. Aborted runs may leave the files with mode 
0222 and the uulog program will not read or remove them. To remove them, either use rm, 
uuclean, or change the mode to 0666 and let uulog merge them into the LOGFILE. 

10.4. STST - System Status Files 

These files are created in the spool directory by the uucico program. They contain information 
such as login, dialup or sequence check failures or will contain a TALKING status when two 
machines are conversing. The form of the file name is 

STST.sys 

where ays is the remote system name, truncated to seven characters. 

For ordinary failures, such as dialup or login, the file prevents repeated tries for about 55 
minutes. This is the default time; it can be changed on an individual system basis by a subfield 
of the time field in the L.sys file. For sequence check failures, the file must be removed before 
any future attempts to converse with that remote system. Retries are accomplished by starting 
uucico from crontaby usually hourly. 
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10.5. LCK - Lock Files 

Lock files are created for each device in use (e.g., automatic calling unit) and each system 
conyersing. This prevents duplicate conyersations and multiple attempts to use the same dev- 
ice. The form of the lock file name is: 

LCK..str 

where etr is either a device or system name. The files may be left in the spool directory if runs 
abort (usually only on system crashes). They are ignored (reused) after 1.5 hours. When runs 
abort and calls are desired before the time limit, the lock files should be removed. 

10.6. Shell Files 

The uucp program spools work and attempts to start the uucieo program, but uueico will not 
always be able to execute the request immediately. Therefore, the uueico program should be 
periodically started. The command to start uucieo can be put in a "shelF* file with a command 
to merge LOG. files and started by a crontab entry on an hourly basis. The file could contain 
the commands: 

/usr/bin/uulog 

progr am/ nvLc'ico -rl -sinter 

proj^ram/uucico -rl 

The "-rl" option is required to start the uueico program in MASTER mode. The "-s" option 
can be used for polling as illustrated in the second line where machine inter is being polled. The 
third line processes all other spooled work. 

Another shell file may be set up on a daily basis to remove TM, ST and LC/C files and C. or D. 
files for work that can not be accomplished for reasons like bad phone number, login changes, 
and so on. A shell file containing commands like: 

proj^ram/uuclean -pTM -pC. -pD. 
program/ nuchdLn -pST -pLCK -nl2 

can be used. Note that the "-nl2" option causes the ST and LCK files older than 12 hours to 
be deleted. The absence of the "-n" option uses a three day time limit. 

A daily or weekly shell should also be created to remove or save old LOGFILE's. A shell like: 

cp «poo//LOGFILE «poo//o.LOGFILE 
rm «poo//LOGFILE 

can be used. 

The shell files in program/ uucp.* do a more extensive job than that described here. They 
should be started by entries in crontab. Read the shell files for more information. 

10.7. Login Entry 

Two or more logins should be set up for uucp. One should be an administrative login: the 
owner of all the uucp programs, directories and files. All others are used by remote systems to 
access the uucp system. Each of the /ete/passwd entries for the access logins should have 
proyram/uucico as the shell to be executed. The login directory should be the public directory 
(usually / usr/ spool/ uucppuhlic) for both the administrative login and the access logins. The 
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various access login names are used in the USERFILE to restrict file access. 

10.8. File Modes 

The programs uucp, uttx, ttucieo, uuhg, uucUan, and uuz^ should be owned by the uucp admin- 
istrative login with the "setuid" bit set and only execute permissions (mode 04111). The L,iy$f 
SQFILE, and the USERFILE, which are put in the program directory should be owned by the 
uucp administrative login and set with mode 0400. The mode of spool should be 0755. The 
mode of xqtdir should be 0777. The L'dialcodts and the L-devices files should have mode 0444. 
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This paper addresses a few (slightly disjunct) topics relevant to system administrators installing, 
converting, or maintaining a network news system. The basic installation and conversion pro- 
cedures are discussed in the body of the System InstaUation and Maintenance Guide; here we 
give more detailed information on usage and maintenance. 

1. Files 

The files in /usr/lib/newa and their functions are: 

active Lists active newsgroups. Each line of the active file contains two fields: the news- 

group name, and the highest local article number (for the most recently received 
article within the newsgroup). The fields are separated by a space. Local article 
numbers begin at 1 and increment as articles are received. They do not usually 
correspond to local article numbers at other sites. The article number is always 
stored as a 5 digit number (with leading zeros) to allow updating of the file in place. 

Active is automatically updated as new newsgroups come in. 

The order of active's list of newsgroups dictates the order in which news will be 
presented by readnews, so you might want to edit active and arrange the news- 
groups accordingly. Here is a recommended order for activr. 

general 

local. general 

net.general 

net. follow up 

local newsgroups, in alphabetical order 

net.all newsgroups, in alphabetical order 

junk 

fa. all, in alphabetical order 

test 

all. test 

to.all 

control 



eaetar Does caesar decoding of rotated text on a line-by-line basis. Caesar copies standard 

input to the standard output, rotating each line according to a static single letter 
frequency table. If an integer argument is given (13, for example, may be used to 
encode material for posting), every line is rotated by that argument, without regard 
for letter frequencies. Call up caesar by using the D readnews command. 
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help Displays a list of legitimate commands when an illegal command is typed to read- 

news. 

history Lists every article received by your system. Used to reject articles that come in for 
the second time (presumably via a different path). The history file will grow, but 
may be cleaned out with the expire command. 

history.dir, kistory.pag 

These two files are used as a hashed version of history; they contain the message 
id's of all articles in the history file. Both files are updated by inews and expire. 

log If present, maintains a log of articles processed and error conditions encountered. 

The log file can grow without limit, so it is cleaned out periodically by running 
rtews.week from cron. 

ngfile Lists newsgroups that you can legally post to locally. Actually, it's a pattern, so if 

you include all it will allow everything. You probably want to forbid fa.aU here, 
for example, since fa. groups are not posted to directly. There is also a mechanism 
for controlling which newsgroups you will accept from other sites — see the section 
on the format of the sys file, below. 

notify Names the user to notify in case of a problem. If the file is empty, nobody is 

notified. The notify file is especially useful if one person administers several sys- 
tems, and does not want multiple copies of control message notifications. 

organization 

Contains (on one line) the name and address of your organization. This informar 
tion is inserted in the articles you post. 

recnews Arranges to send mail to post news. 

recording Lists newsgroup classes and file names to display recordings for. Recordings on cer- 
tain newsgroups are intended to remind the user of the rules for the newsgroup; in 
the case of a certain companies, recordings may be used to remind news authors to 
protect proprietary information. 

Recording contains one line per recording. Each line contains two fields, separated 
by a space. The first field is the newsgroup class (net.all, for example); the second 
field is the name of the file containing the recorded message. If the file name does 
not begin with a slash, it is searched for in /usr/ lib/ news. 

sendnews Sends news internally from one computer to another. Useful if you use mail links 
to transmit articles. 

seq Contains the current sequence number for your system. Used to generate unique 

article ID's. 

sys Lists all your neighbors, which newsgroups they subscribe to, and how to send news 

to them. Sys^s format is documented below. 

users Lists users who read news on your system. 

uureq Receives news sent by sendnews. 

1.1. File Modes and Permissions 

The current intended state of affairs is that inews runs set-user-id (suid) news. The readnews 
program does not need to be set-user-id. This makes it possible to write your own interface to 
read news instead of using readnews. 
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All the files in /usr/ spool/ news should be writable by the "news" user. 

1.2. Format of the sys File 

To set up a link to another site (the two types of links are discussed below), you edit 
/usr/ lib/ news/ sys. Sys is similar to the UUCP L.sys file. Each line contains four fields; fields 
are separated by colons: 

(1) The system name of a site to which you forward news. Normally, you should include a line 
for all systems you have links to, as well a line for your own system. 

(2) The newsgroups to be forwarded to them. This is a pattern in the sense of a subscription. 
Generally, you will list classes of newsgroups, that is, using all for everything. A typical 
forwarding list for a new site would be: 

net.all,fa.all,to.sysname 

where sysname is the name of your contact site. Note that you should not forward all, in 
particular, since local newsgroups (those without dots) should not be sent. In the line 
describing your own system, this field describes the newsgroups your site will accept from 
contact sites. Thus, if another site insists on sending you a newsgroup you don't want, say 
net.jokes, include tnet.jokes here. 

(3) Flags describing the connection between sites. These are: 

A Indicates that the contact site is running an A version of netnews, or 

B The contact site is running a B version. If neither A nor B is indicated here, default is 
B. If you are running the latest release of Sun software, you have a B version. If you 
aren't sure which version your contact site is running, ask them before proceeding. 

F Indicates that the fourth field is the name of a file. The full path name of a file contain- 
ing the article in /usr/ spool/ news will be appended to this file. 

L Prevents transmission unless the article was created on this site. Feeding an L link to a 
backbone site ensures that your submissions will be more likely to get to the entire net- 
work, even in the event of a local problem. Please make sure that a mail link exists too, 
so you can get replies. 

U Arranges that the parameter to the optional %9 in the command field be filled in with a 
permanent file name from /usr/ spool/ news instead of a temporary customized file name. 

(4) The command to be run to send news to the remote site. The article will be on the stan- 
dard input. A %s in the command will be replaced with the name of the file that contains 
the article. Leaving this field blank means an ordinary UUCP link is being used, that is, 
the command defaults to: 

uux r — * sysnamelrn&w» 

Options here are: 

- Tells uux to expect input on stdin. 

-r Tells uux not to start up a daemon right away. This eases the load on the system, and 
makes news transmission only a bit slower. News is sent when the next daemon is 
started, usually the next time uucico is invoked by cron, 

-M Shuts off the annoying message you would otherwise get mailed to you telling you that 
your article was successfully broadcast. The — b option is nonstandard; the remote sys- 
tem may need to be modified to understand it. To avoid using -b, put the uux com- 
mand in the fourth field. 
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Here is a sample syt file for a site "zenith" with connections to *'nadir". ''Nadir" also passes 
news on to "lowerreaches". We assume that "zenith" and "lowerreaches" exchange a local 
newsgroup class Ing.all as well as the network wide newsgroups. News to "lowerreaches" is 
batched. 

zenith:net.all,fa.all,Ing.all:: 

nadir:net.all,fa.all:: 

lowerreaches:net.all,fa.all,lng.all:F:/usr/spool/batch/lowerreaches 



2. Setting up Links 

There are two basic types of links for exchanging news: those that use mail and those that 
don't. The ones that use mail are more indirect, yet more versatile; the ones that don't are 
simpler. The default type is without mail, so we discuss it first. 

2.1. Non-mail Links 

The basic theory behind a non-mail link is that the rnews program is invoked on the remote 
system with the article being transmitted as the standard input. This is possible on various 
networks, but the most common implementation is via the UUCP network. Using the ittf2(lC) 
command, the command which is forked to the shell looks like: 

uux r — « remotesyslrnev/B < articUname 

This is the default transmission method. In order to set up such a link, obviously a UUCP link 
with the remote system must be in effect. In addition, rtiewi must be available and executable 
by uuxqt on the remote machine. In most cases, this means that rnewt must be in /u$r/bin so 
uux can find it. 



2.2. Mail Links 

When using mail to transmit articles, two intermediary programs are necessary: tendnewi{S) 
and uurec{8). The mail link works as follows. First, the folks at system A arrange to run iend- 
news on articles they wish to send to system B by placing an entry like the following in the tys 
file on system A: 

/usr/lib/news/sendnews -a rnews@B 

The -a option specifies that the mail should be formatted for the arpanet. When someone at 
system A sends an article to system B, sendnew* packages the article and mails it to rnews^B. 
Somehow, system B must make sure that all mail to user "rnews" is fed as input to the uurec 
program. The best way to make this happen is to use sendmail or delivermailf if you are on a 
system running them. So the system B administrator creates an alias in /uar/lib/iUiase* like 
this: 

rnews: " l/usr/lib/news/uurec" 

When uurec receives the article, it unpackages the article and invokes rnewi. 
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3. Posting Methods 

There are three ways to post news. The basic method is to use the inewt command: 
% inews -t title —n newigroups < bodyfile 

This is the primitive used by other programs, and is not very suitable for humans. 

A somewhat friendlier front end is postnews. Postnew* first prompts for article header lines: 
title, newsgroups, and distribution, and then places you in the editor so you can enter the text 
of your article. The system default EDITOR (/u»r/ucb/vi) is used unless the environment vari- 
able EDITOR is set to override the system default. The header lines you entered at the begin- 
ning of the session remain available for editing at the top of the buffer; other header lines can 
also be added, such as expiration date. When you write out the file and exit from the editor, 
your article is posted. 

Another method is to use mail. This is possible with Sun systems. To use mail, set up an alias 
such as the following for each newsgroup you subscribe to (adding new groups as they are 
created): 

net.general: " |/usr/lib/news/recnews net.general" 

Now, whenever you send mail to net.general this starts up the given shell command which 
calls recnews with one argument: the name of the newsgroup. Recnewt will in turn invoke 
inews. 

Note that there are limits to recnews. There is no way to use it to post to multiple newsgroups 
without creating separate articles (something frowned upon because it forces people to read the 
same thing more than once). Nor is there any way to make the recording feature work when 
recnews is used (see the Files section above). 

4. Control Messages 

Some news systems send articles that are not for human consumption. These articles are mes- 
sages to your news system called "control messages." 

A control message begins with a "Control:" header, the subject of the article contains a com- 
mand and zero or more arguments (much like a UNIX program), and the body of the article 
may be used for additional text. A list of commands follows. 

Older systems use newsgroups matching all.all.ctl, rather than the "Control:" header, and this 
will still work, although the "Control:" header is preferred. Since the newsgroup name is used 
for distribution only, and is not checked to ensure that it*s in the active file, such newsgroup 
names can still be used. This makes it possible to post network-wide control messages with 
net.msg.ctl (or restricted broadcast such as btl.msg.ctl) or messages for a particular system: 
to.ucbvax.ctl. Messages are cancelled with a "Control:" line in a message to the same 
newsgroup(s) as the original message. 

Control messages are not stored in /usr/ spool/ news; rather they are acted on and discarded at 
once. 

Control message commands are: 

newgroup Allows special action to be taken locally when a new newsgroup is created. The 
group itself is created with the inews command with the — C option, and this gen- 
erates the message. By default, the newsgroup is added to the active file, a direc- 
tory is created for it, and mail is sent to the local contact advising that this has 
happened, newgroup takes one argument: the name of the newsgroup to be 
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created. 

rmgroup Cancels a newsgroup network-wide. Rmgroup takes one argument: the name of 
the newsgroup to be removed. There is also a shell script, ^^rmgrp^^ that cancels a 
newsgroup locally. We recommend that when you receive mail advising you of the 
demise of a newsgroup, you run rmgrp by hand; this prevents accidental or mali- 
cious removal of a good newsgroup. 

cancel Cancels a given article. Cancel should be broadcast to the same newsgroup as the 

original article. Cancel takes one argument: the message ID of the article to can- 
cel. 

sendsys Mails the sys file to the originator of the message — used for making maps. 

Sendays takes no arguments. 

senduuname Runs uuname{l) and mails the output to the originator of the message — used for 
making UUCP maps. Senduuname takes no arguments. 

version Mails the local version name/number of the netnews software to the originator of 

the message. 

Other Messages 

Any unrecognized message will cause an error message to be mailed to the origina- 
tor. Additional messages may be defined as time goes on, such as messages to 
automatically update directories or maps. 

5. Maintenance 

There are a few things you should set up at the outset, and a few that you must do periodically, 
to keep your news system running smoothly. We hope to eventually automate all or most of 
this, but right now some of it must be done by hand. 

To get articles to expire automatically, put the following line in crontab: 

7 * * 2 su news < /usr/lib/news/news.week 

This runs a shell script which runs expire{S) to delete all expired news. The -a option to expire 
archives all expired news under / uar/ spool/ oldnews. 

Sometimes news has not expired when it should have. If this seems to be happening, make sure 
that expire has permissions to unlink files, that it runs as a user that has a .newsrc, and that it 
is properly suid. You can manually invoke expire with the — v (verbose) option to find out what 
it's doing. Adding levels of verbosity (for example, "-v6") generates more and more output. 

The history and log files in your /usr/lib/newa directory will grow and must be cleaned out 
periodically. The /usr/lib/newa/ expire program removes lines from history corresponding to 
deleted articles, but it is a good idea to check the file every few months to make sure it is not 
going wild. Be sure not to completely lose your history file when you clean it up, in case a neigh- 
bor tries to send you an article you received recently. If you only get news from one site, it is 
safe to clean hiatory out completely. 

The log file is not automatically cleaned out by any netnews software, and will grow quickly. 
The newa.week entry to /uar/ lib/ crontab noted above, however, will take care of cleaning the log 
file in addition to deleting expired articles. 

You should also clean out old newsgroups that are no longer active. To remove a newsgroup, 
use the / uar/ lib/ newa/ rmgrp shell script. 
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Another task you^l probably have to undertake is clearing up UUCP constipation. If you have 
more than one connection, chances are that UUCP will get clogged up when one of your neigh- 
bors goes down for more than a few hours. Various spooling schemes are being worked on to 
help make the news/UUCP system more robust. Right now, UUCP is the weak link in netnews 
distribution, and you should certainly keep an eye on it. 

6. Creating New Newsgroups 

As system news administrator, you can create news^oups. Before creating a newsgroup, first 
make sure this is the right thing to do. Normal etiquette runs as follows: a suggestion is first 
posted to net.genera!,net.new8.group for a net newsgroup, followups are made to 
net.news.group, it is established if there is general interest in such a group, and a name is 
agreed on. Then you (as user '^news'') can create the newsgroup network-wide by typing the 
command: 

% inews -C newsgroup 

This creates the newsgroup directory and active entry locally. It also prompts you for a para- 
graph describing the group, and starts up inews to post a newgroup control message announcing 
the group. This control message is sent out on net.msg.ctl; other sites may have configured 
their systems to do something with these messages. A human readable announcement is not 
made — you can post one to net.news.group if you wish. 

You should make sure a first article is posted to the new newsgroup immediately. If this is not 
done, checknews will see the empty newsgroup directory and believe there is unread news (as 
each user lacks a ".newsrc" line for the newsgroup). 

7. Differences between Version 2.9 and 2.10 

Both versions 2.9 and 2.10 are *B' Versions of USENET format (just to confuse you). Version 
2.9 was released with the Sun 0.4 and earlier software distributions; version 2.10 is released with 
Sun 1.0 and the current distributions. Differences between versions 2.9 and 2.10 follow; the sec- 
tion after this one discusses the differences between versions A and B of the USENET software. 

New File Storage Format 

The file storage format has been changed. 

Rather than storing news in / usr/ spool/ news/ net. games.rogue/ 183, an article now goes in 
/usr/ spool/ news/ net/ games/ rogue/ 123. This allows newsgroup names to be longer than 14 
characters and still have subgroups. It also makes directories smaller, resulting in faster 
performance. The dot files are gone: rather than saving the next article number in 
/usr/ spool/ news/ .net. games.rogue as the length of the file, it goes in the active file on the 
same line as net. games. rogue. Thus, your active file contains lines like 

net .games .rogue 00123 

where the newsgroup name and the max article number are separated by a space. The arti- 
cle numbers are ALWAYS 5 digits long and include the leading digits to do this (this is so 
they can be updated in place without growing the active file). 

This conversion of directory tree formats has an extra benefit. You^ll find that readnews is 
now considerably faster than in version 2.9. The movement of the dot files accounts for 
much of this, since it is no longer necessary to "stat" every dot file. Additionally, a routine 
to find a newsgroup in your .newsrc has been modified to keep the file sorted in the same 
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order as active, and a "last found" pointer is used to reduce the find time algorithm from 
quadratic complexity (on the number of newsgroups) to linear complexity. This makes the 
total number of newsgroups less of a factor in determining speed, and also keeps everyone's 
.newsre cleaned out. It is important that people not store extra junk in their .newsrc, 
because it will be deleted when they run readnewt. 

New Hashed History 

The method used to determine if an incoming article has already been seen locally has been 
changed. On V7 systems, profiling showed that rnewt spent about half of its time in fgets 
reading the history file. It now uses the dbm{S) library to hash the message ID of each arti- 
cle. To avoid incompatibilities between 2.9 and 2.10, if you have more than one incoming 
news feed, run the provided cvt.hist program (see the Conversion section for the script), 
which will enter all the message ID*s from your 2.9 format history file into the hashed data- 
base. The text history file is maintained as it was in 2.9, for human use. 

New Message Header Format 

Message headers now meet the USENET format standard* and RFC822. Headers stored 
will look verbose, and contain much more information. Headers transmitted to other sys- 
tems will work with old B news systems or new ones. The format of dates has been 
changed to conform to RFC822. 

New User Interface 

The user interface is roughly compatible, but you will notice a few differences, and there are 
a few extensions. One major difference is that pottnews now prompts for a "Distribution". 
This defaults to the same as the newsgroup (and is omitted in this case), but allows you to 
conveniently enter a Distribution header line (and makes you think twice about where your 
message is going to). Any newsgroup name(s) can be typed here, but one normally types 
either nothing or a class distribution ("net", "btl", "nj", or "world", for example), restrict- 
ing the distribution to that class of sites. 

A more minor change: headers are now displayed in a format which is more compact, but 
more information is displayed than before. If you want to see the article ID or full path, or 
the date or newsgroups, use the h command for a display. The H command can be used for 
a full, verbose header dump. 

Changed Control Messages 

Control messages are slightly different. In particular, 2.10 now requires that a newsgroup be 
created with a newgroup control message (generated by inews ~C) before it can be used. If 
an incoming article is in some newsgroup that is not in the local active file, the article will 
be stored locally in newsgroup junk and not forwarded to other systems. This will prevent 
the accidental creation of typographical errors by systems running older versions of news. 

Also, the rmgroup control message has been made less dangerous. When an rmgroup mes- 
sage comes around, you will be sent mail asking you to remove the group, but the group 
will not actually be removed. This prevents someone from accidently or deliberately remov- 
ing an important newsgroup such as net.general. 



• Document available from Sun Microsystems: Standard for Interchange of USENET Me9tage», part 
number 800-1097-01. 
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Archiving 

Expire used to automatically archive news in j uirj tpoolj olintwt if that directory existed; 
it now archives news only if you supply the —a option. 

Sharing News Software 

When you connect to a new site, you must now send a copy of your active file, so that the 
appropriate newsgroup directories and active file can be built. This was not necessary in 2.0 
because unrecognized incoming newsgroups were automatically created, but they are thrown 
away in 2.10. 

New Programs 

Some new programs have been added to /usr/ lib/ newt. These include recmail and caesar. 
Recmail takes a mail message on stdin, figures out who the To: and Cc: lines refer to, and 
invokes /bin/mail with those arguments (not changed) and with the file on stdin. Recmail 
is used by the reply command. Caesar decodes rotated jokes; it can also be used to create 
rotated jokes. 

New Mail Batching Provisions 

Version 2.10 has some experimental batching provisions in it. See the batch and unbatch 
programs, and the F and U options in the syt file, for more details. All this is very new, and 
while it appears to run satisfactorily, caution is advised in installing batching software. 
You must also make sure your neighbor is prepared to receive batched news; this is nor- 
mally true if the neighbor is running at least 2.10. 

8. Version A Versus Version B 

Version B automatically understands incoming news in either version A or B format. Version B 
generates either format, depending on the flag in the third field of the description line of the tyt 
file. Thus, it would be possible for two version B sites to communicate using version A format 
— though it would not be a good idea, since the translation from B to A results in a permanent 
loss of some header information (such as expiration date). 

Version A does not understand version B format. 

News from versions A and 2.9 B do not conform to the USENET interchange standard. 2.10 
supports the standard and will communicate with either A or 2.9 B news. 2.10 will write out 
headers with both standard (Date, Message-ID) and 2.9 (Posted, Article-I.D.) lines so that either 
B system will properly handle the article. Incoming news is recognized by the first letter ("A" 
for A news), or the lack of an '^©'^ in the From line (2.9). Missing fields are constructed as well 
as possible from the available information. 
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This document describes the structure and installation procedure for the line printer spooling 
system implemented in this release of the Sun UNIX'^ operating system. 

1 . Overview 

The line printer system supports: 

• multiple printers, 

• multiple spooling queues, 

• both local and remote printers, and 

• printers attached via serial lines which require line initialization such as the baud rate. 

Raster output devices such as a Varian or Versatec, and laser printers such as an Imagen, are 
also supported by the line printer system. 

The line printer system consists mainly of the following files and commands: 

etc/printcap printer configuration and capability data base 

usr/lib/lpd line printer daemon, does all the real work 

usr/ucb/lpr program to enter a job in a printer queue 

usr/ucb/lpq spooling queue examination program 

usr/ucb/lprm program to delete jobs from a queue 

etc/lpc program to administer printers and spooling queues 

dev/printer socket on which Ipd listens 

The file /etc/printcap is a master data base describing line printers directly attached to a 
machine and, also, printers accessible across a network. The manual page entry printeap{S) pro- 
vides the ultimate definition of the format of this data base, as well as indicating default values 
for important items such as the directory in which spooling is performed. This document 
highlights the important information which may be placed in printcap. 

2. Commands 



2.1. Ipd — line printer daemon 

The program lpd(S), usually invoked at boot time from the /etc/ re file, acts as a master server 
for coordinating and controlling the spooling queues configured in the printcap file. When Ipd is 
started it makes a single pass through the printeap database restarting any printers which have 
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jobs. In normal operation Ipd listens for service requests on multiple sockets, one in the UNIX 
domain (named ^^/dey/pnnieT^^) for local requests, and one in the Internet domain (under the 
"printer^^ service specification) for requests for printer access from off machine; see tocket(2) and 
services (S) for more information on sockets and service specifications, respectively. Lpd spawns 
a copy of itself to process the request; the master daemon continues to listen for new requests. 

Clients communicate with lpd using a simple transaction oriented protocol. Authentication of 
remote clients is done based on the "privilege port" scheme employed by r»hd{SC) and 
rcmrf(3X). The following table shows the requests understood by lpd. In each request the first 
byte indicates the "meaning" of the request, followed by the name of the printer to which it 
should be applied. Additional qualifiers may follow, depending on the request. 



Request 



Interpretation 



*Aprinter\n 
* Bprinter\n 
'Cprinter [users 
'Dprinter [users 



[jobs ...]\n 
[jobs ...l\n 



check the queue for jobs and print any found 
receive and queue a job from another machine 
return short list of current queue state 
return long list of current queue state 



Eprinter person [users ...] [jobs ...]\n remove jobs from a queue 



The /pr(l) command is used by users to enter a print job in a local queue and to notify the local 
lpd that there are new jobs in the spooling area. Lpd either schedules the job to be printed 
locally, or in the case of remote printing, attempts to forward the job to the appropriate 
machine. If the printer cannot be opened or the destination machine is unreachable, the job will 
remain queued until it is possible to complete the work. 

2.2. Ipq - show line printer queue 

The lpq{l) program works recursively backwards displaying the queue of the machine with the 
printer and then the queue(s) of the machine(s) that lead to it. Lpq has two forms of output: in 
the default, short, format it gives a single line of output per queued job; in the long format it 
shows the list of files, and their sizes, which comprise a job. 

2.3. Iprm - remove jobs from a queue 

The lprm{l) command deletes jobs from a spooling queue. If necessary, Iprm will first kill off a 
running daemon which is servicing the queue, restarting it after the required files are removed. 
When removing jobs destined for a remote printer, Iprm acts similarly to lpq except it first 
checks locally for jobs to remove and then tries to remove files in queues off-machine. 

2.4. Ipc — line printer control program 

The lpc{S) program is used by the system administrator to control the operation of the line 
printer system. For each line printer configured in /etc/printcapy Ipc may be used to: 

• disable or enable a printer, 

• disable or enable a printer's spooling queue, 

• rearrange the order of jobs in a spooling queue, 
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• find the status of printers, and their associated spooling queues and printer dameons. 

3. Access Control 

The printer system maintains protected spooling areas so that users cannot circumvent printer 
accounting or remove files other than their own. The strategy used to maintain protected spool- 
ing areas is as follows: 

• The spooling area is writable only by a daemon user and daemon group. 

• The Ipr program runs setuid root and setgid daemon. The root access is used to read any file 
required, verifying accessibility with an acces${2) call. The group ID is used in setting up 
proper ownership of files in the spooling area for Iprm. Data files are owned by user, group 
daemon, mode 660. 

• Control files in a spooling area are made with daemon ownership and group ownership dae- 
mon. Their mode is 0660. This insures control files are not modified by a user and that no 
user can remove files except through Iprm. 

• The spooling programs, Ipd, Ipq, and Iprm run setuid root and setgid daemon to access spool 
files and printers. 

• The printer server, Ipd, uses the same verification procedures as rshd{8C) in authenticating 
remote clients. The host on which a client resides must be present in the file 
/etc/hosts.equiv, used to create clusters of machines under a single administration. 

In practice, none of Ipd, Ipq, or Iprm would have to run as user root if remote spooling were not 
supported. In previous incarnations of the printer system Ipd ran setuid daemon^ setgid spool- 
ing, and Ipq and Iprm ran setgid spooling. 

4. Setting Up 

The Sun system release comes with the necessary programs installed and with the default line 
printer queue created. The real work in setting up is to create the printcap file and any printer 
filters for printers not supported in the distribution system. 

4.1. Creating a Printcap File 

The printcap database contains one or more entries per printer. A printer should have a 
separate spooling directory; otherwise, jobs will be printed on different printers depending on 
which printer daemon starts first. This section describes how to create entries for printers 
which do not conform to the default printer description. 

4.1.1. Printers on Serial Lines 

When a printer is connected via a serial communication line it must have the proper baud rate 
and terminal modes set. The following example is for a DecWriter III printer connected locally 
via a 1200 baud serial line. 
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lp|LA-180 DecWriter III:\ 

:Ip=/dev/lp:br#1200:fs#06320:\ 
:tr=\f:of=/usr/lib/lpf:lf=/usr/adm/lpd-crrs: 

The Ip entry specifies the file name to open for output. In this case it could be left out since 
"/dev/lp" is the default. The br entry sets the baud rate for the tty line and the fs entry sets 
CRMOD, no parity, and XTABS (see tty(4)). The tr entry indicates a form-feed should be 
printed when the queue empties so the paper can be torn off without turning the printer off-line 
and pressing form feed. The of entry specifies the filter program Ipf should be used for printing 
the files; more will be said about filters later. The last entry causes errors to be written to the 
file "/usr/adm/lpd-errs" instead of the console. 

4.1.2. Remote Printers 

Printers which reside on remote hosts should have an empty Ip entry. For example, the follow- 
ing printcap entry would send output to the printer named 'ip" on the machine "ucbvax". 

Ip [default line printer :\ 

:lp=:rm=ucbvax:rp=lp:sd=/usr/spool/vaxlpd: 

The rm entry is the name of the remote machine to connect to; this name must appear in the 
/etc/hosts database, see hosts (b). The rp capability indicates the name of the printer on the 
remote machine is "Ip"; in this case it could be left out since this is the default value. The sd 
entry specifies "/usr/spool/vaxlpd" as the spooling directory instead of the default value of 

"/usr/spool/lpd". 

4.2. Output Filters 

Filters are used to handle device dependencies and to perform accounting functions. The out- 
put filter of is used to filter text data to the printer device when accounting is not used or when 
all text data must be passed through a filter. It is not intended to perform accounting since it 
is started only once, all text files are filtered through it, and no provision is made for passing 
owners' login name, identifying the begining and ending of jobs, etc. The other filters (if 
specified) are started for each file printed and perform accounting if there is an af entry. If 
entries for both of and one of the other filters arc specified, the output filter is used only to 
print the banner page; it is then stopped to allow other filters access to the printer. An example 
of a printer which requires output filters is the Benson- Varian. 

va|varianjBenson-Varian:\ 

:lp=/dev/vaO:sd==/usr/spool/vad:of=/usr/lib/vpf:\ 
:tf=/usr/Iib/rvcat:mx#2000:pl#58:tr=\f: 

The tf entry specifies ^'/Msr/lih/TYCSkV^ as the filter to be used in printing troff(l) output. This 
filter is needed to set the device into print mode for text, and plot mode for printing troff files 
and raster images (see vp(4S)). Note that the page length is set to 58 lines by the pi entry for 
S.5^ by ll'' fan-fold paper. To enable accounting, the varian entry would be augmented with 
an &f filter as shown below. 
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va|varian|Benson-Varian:\ 

:lp=/dev/vaO:sd=/usp/spool/vad:of=»/usr/lib/vpf:\ 

:if=/usr/lib/vpf:tf=/usr/lib/rvcat:af=/usr/adm/vaacct:\ 

:mx#2000:pl#58:tr=\f: 



5. Output Filter Specifications 

For most devices or accounting methods, it is probably necessary to create a new filter. 

Filters are spawned by Ipd with their standard input the data to be printed, and standard out- 
put the printer. The standard error is attached to the If file for logging errors. A filter must 
return a exit code if there were no errors, 1 if the job should be reprinted, and 2 if the job 
should be thrown away. When Iprm sends a kill signal to the Ipd process controlling printing, it 
sends a SIGTERM signal to all filters and descendents of filters. This signal can be trapped by 
filters which need to perform cleanup operations such as deleting temporary files. 

Arguments passed to a filter depend on its type. The of filter is called with the following argu- 
ments. 

filer — wwidth -Uength 

The width and length values come from the pw and pi entries in the printcap database. The if 
filter is passed the following parameters. 

filter [-c] -wwidth -Uength -iindent -n login — h host accounting_file 

The -c flag is optional, and only supplied when control characters are to be passed uninter- 
preted to the printer (when the —1 option of Ipr is used to print the file). The — w and —1 
parameters are the same as for the of filter. The — n and -h parameters specify the lo^n name 
and host name of the job owner. The last argument is the name of the accounting file from 
printcap. 

All other filters are called with the following arguments: 

filter — xwidth — ylength — n log^n — h host accountingjGle 

The -X and -y options specify the horizontal and vertical page size in pixels (from the px and 
py entries in the printcap file). The rest of the arguments are the same as for the if filter. 

6. Line Printer Administration 

The Ipc program provides local control over line printer activity. The major commands and 
their intended use will be described. The command format and remaining commands are 
described in lpc{S). 

abort and start 

Abort terminates an active spooling daemon on the local host immediately and then dis- 
ables printing (preventing new daemons from being started by Ipr). This is normally used 
to force a hung line printer daemon to restart (i.e., Ipg reports that there is a daemon 
present but nothing is happening). It does not remove any jobs from the queue (use the 
Iprm command instead). Start enables printing and requests Ipd to start printing jobs. 

enable and disable 
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Enable and disable allow spooling in the local queue to be turned on/o£f. This will 
allow /prevent Ipr from putting new jobs in the spool queue. It is frequently convenient to 
turn spooling off while testing new line printer filters since the root user can still use Ipr to 
put jobs in the queue but no one else can. The other main use is to prevent users from put- 
ting jobs in the queue when the printer is expected to be unavailable for a long time. 

restart 

Restart allows ordinary users to restart printer daemons when Ipq reports that there is no 
daemon present. 

stop 

Stop is used to halt a spooling daemon after the current job completes; this also disables 
printing. This is a clean way to shutdown a printer in order to perform maintenence, etc. 
Note that users can still enter jobs in a spool queue while a printer is stopped. 

topq 

Topq places jobs at the top of a printer queue. This can be used to reorder high priority 
jobs since Ipr only provides first-come-first-serve ordering of jobs. 

7. Troubleshooting 

There are a number of messages which may be generated by the the line printer system. This 
section categorizes the most common and explains the cause for their generation. Where the 
message indicates a failure, directions are given to remedy the problem. 

In the examples below, the name printer is the name of the printer. This would be one of the 
names from the printcap database. 



LPR 



Ipr: printer t unknown printer 

The printer was not found in the printcap database. Usually this is a typing mistake; how- 
ever, it may indicate a missing or incorrect entry in the /etc/printcap file. 

Ipr: printer: jobs queued, but cannot start daemon. 

The connection to Ipd on the local machine failed. This usually means the printer server 
started at boot time has died or is hung. Check the local socket /dev/printer to be sure it 
still exists (if it does not exist, there is no Ipd process running). Use 

% ps ax I fgrep Ipd 

to get a list of process identifiers of running Ipd's. The ipd to kill is the one which is not 
listed in any of the "lock" files (the lock file is contained in the spool directory of each 
printer). Kill the master daemon using the following command. 

% kill pid 

Then remove /dev/printer and restart the daemon (and printer) with the following com- 
mands. 

% rm /dev/printer 
% /usr/lib/lpd 
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Another possibility is that the Ipr program is not setuid root, setgid tpooUng. This can be 
checked with 

% Is -Ig /usr/ucb/lpr 

Ipr: printer; printer queue is disabled 
This means the queue was turned off with 

% Ipc disable printer 

to prevent Ipr from putting files in the queue. This is normally done by the system 
manager when a printer is going to be down for a long time. The printer can be turned 
back on by a super-user with Ipc. 



LPQ 



waiting for printer to become ready (offline ?) 

The printer device could not be opened by the daemon. This can happen for a number of 
reasons, the most common being that the printer is turned off-line. This message can also 
be generated if the printer is out of paper, the paper is jammed, etc. The actual reason is 
dependent on the meaning of error codes returned by system device driver. Not all printers 
supply sufficient information to distinguish when a printer is off-line or having trouble (e.g. 
a printer connected through a serial line). Another possible cause of this message is some 
other process, such as an output filter, has an exclusive open on the device. Your only 
recourse here is to kill off the offending program(s) and restart the printer with Ipe. 

printer is ready and printing 

The Ipq program checks to see if a daemon process exists for printer and prints the file 
status. If the daemon is hung, a super user can use ipc to abort the current daemon and 
start a new one. 

waiting for host to come up 

This indicates there is a daemon trying to connect to the remote machine named host in 
order to send the files in the local queue. If the remote machine is up, tpd on the remote 
machine is probably dead or hung and should be restarted as mentioned for Ipr. 

sending to host 

The files should be in the process of being transferred to the remote host. If not, the local 

daemon should be aborted and started with Ipc. 

Warning: printer is down 

The printer has been marked as being unavailable with Ipc. 

Warning: no daemon present 

The tpd process overseeing the spooling queue, as indicated in the "lock" file in that direc- 
tory, does not exist. This normally occurs only when the daemon has unexpectedly died. 
The error log file for the printer should be checked for a diagnostic from the deceased pro- 
cess. To restart an (prf, use 

% Ipc restart printer 

Iprm: printer; cannot restart printer daemon 

This case is the same as when Ipr prints that the daemon cannot be started. 
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LPD 

The Ipd program can write many different messages to the error log file (the file specified in the 
If entry in printcap). Most of these messages are about files which can not be opened and usu- 
ally indicate the printcap file or the protection modes of the files are not correct. Files may 
also be inaccessible if people manually manipulate the line printer system (i.e. they bypass the 
Ipr program). 

In addition to messages generated by Ipd, any of the filters that Ipd spawns may also log mes- 
sages to this file. 



LPC 



could 't start printer 

This case is the same as when Ipr reports that the daemon cannot be started. 

cannot examine spool directory 

Error messages beginning with '^cannot ..." are usually due to incorrect ownership and/or 

protection mode of the lock file, spooling directory or the Ipe program. 
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